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How to Use This Publication 



This publication provides a full description of the use of the OS/VS (Virtual 
Storage) utility programs. This publication assumes that the reader is familiar 
with vs terms and concepts. 

Effective use of this publication requires an understanding of the following: 

• Organization of the publication as a whole. 

• Organization of each program description. 

• Use of special referencing aids that help you find the right utility program and 
the right example. 

• Required publications. 

• Related publications. 

• Notational conventions used to describe the syntax (or format) of utility 
control statements. 

These topics are discussed below. 



Organization of the Publication 



In addition to the preface you are now reading, a table of contents, a list of 
figures, and a list of tables, this publication has the following major parts: 

• "Summary of Major Changes for vsi Release 3 and VS2 Release 2," which is 
a summary of the major technical changes reflected in this edition. 

• "Guide to Utility Program Functions," which is a table arranged in 
alphabetical order of utility program functions and the programs that perform 
them. This table enables you to get to the program that can do what you need 
to have done. For additional information, see "Special Referencing Aids" 
below. 

• "Introduction," which introduces the utility programs and provides information 
on the differences among system, data set, and independent utility programs. 
This chapter contains basic information about how the programs are executed 
and about the utility control statements used to specify program functions. 
New or infrequent users of the utility programs should give particular attention 
to this chapter. 

• Individual chapters for each utility program and two chapters per program 
when significant differences exist between vsi and VS2. These chapters are in 
alphabetical order, beginning with IBCDASDI and ending with IFHSTATR. For a 
discussion of the organization of these chapters, which will help you find the 
information you need about a particular program, see "Organization of 
Program Descriptions" below. 

• "Appendix A: Exit Routine Linkage," which provides information about 
linking to and returning from optional user-supplied exit routines. This 
appendix should be read only if you plan to code or use an exit routine. If you 
are coding an exit routine, this appendix provides linkage conventions, 
descriptions of parameter lists, and return codes. If you are using an existing 
exit routine, you may be interested in the meaning of return codes from the 
exit routine. 
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• "Appendix B: Invoking Utility Programs from a Problem Program," which 
describes the macro instructions used to invoke a utility program from a 
problem program rather than executing the utility program by job control 
statements or by a procedure in the procedure library. This appendix should 
be read only if you plan to invoke a utility program from a problem program. 

• "Appendix C: DD Statements for Defining Mountable Devices," which 
provides a review of how to define mountable volumes to ensure that no one 
else has access to them. For a definitive explanation of this subject, see OS/VS 
JCL Reference, GC28-0618. 

• "Appendix D: Processing User Labels," which describes the user-label 
processing that can be performed by IEBGENER, IEBCOMPR, IEBPTPCH, 
IEHMOVE, IEBTCRIN, and IEBUPDTE. This appendix should be read only if 
you plan to use a utility program for processing user labels. 

• "Index," which is a subject index to this publication. 

Note: Information on Generation Data Groups previously found in an Appendix 
of this publication is now located in OS/VS Data Management Services Guide, 
GC26-3783, and OS/VS Access Method Services, GC35-0009. 

Organization of Program Descriptions 

Program descriptions are organized, as much as possible, the same way to enable 
you to find information more easily. Most programs are discussed according to 
the following pattern: 

• Introduction to and description of the functions that can be performed by the 
program. This description typically includes an overview of the program's use, 
definitions of terms, illustrations, etc. 

• Input and output (including return codes) used and produced by the program. 

• Control of the program through job control statements and utility control 
statements. A brief explanation of the job control statements used to execute 
the program appears in a table under "Job Control Statements." Any 
restrictions on job control statements appear under a "Restrictions" heading. 
The utility control statements are introduced in a list under "Utility Control 
Statements" so that you can determine which of the statements are required 
for the task to be performed. 

• Examples of using the program, including the job control statements and 
utility control statements. 

Special Referencing Aids 

Two special referencing aids are included in this publication to help you: 

1. Locate the right utility program. 

2. Locate the right example. 

To locate the right utility program, refer to Table 1 in "Guide to Utility Program 
Functions," which immediately precedes the "Introduction. "Figure 1 shows a 
portion of the table. The figure shows that you can use IEHINITT to label a 
magnetic tape volume or IEHLIST to list a volume table of contents. 
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Label magnetic tape volumes IEHINITT 

List a password entry IEHPROGM 

a volume table of contents IEHLIST 

partitioned directories IEHLIST 

Figure 1. Locating the Right Program 



To locate the right example, use the table — called an "example directory" — that 
precedes each program's examples. Figure 2 shows a portion of the example 
directory for IEHMOVE. The figure shows that IEHMOVE Example 1 is an 
example of moving a sequential data set and that IEHMOVE Example 2 is an 
example of copying a sequential data set. 



MOVE Sequential 



COPY Sequential 



3330 Disk, 
2314 Disks 

3330 Disk, 
2314 or 
2319 Disks 



Figure 2. Locating the Right Example 



Source volume is demounted 
after job completion. 
Two mountable disks. 

Three cataloged sequential 
data sets are to be copied. 
The 2314 or 2319 are 
mountable. 



Required Publications 



Related Publications 



The reader should be familiar with the following publications: 

• OS/VS Messages Library: Utilities Messages, GC38-1005, which contains a 
complete listing and explanation of the messages and codes issued by the 
utility programs. 

• OS/VS JCL Reference, GC28-0618, which contains a complete explanation of 
the job control statements available for the operating system. 

• OS/VS Data Management Services Guide, GC26-3783, which describes the 
input/output facilities of the operating system. It contains information on 
record formats, data set organization, access methods, direct access device 
characteristics, data set disposition, space allocation, and generation data sets. 

• 0S/VS1 Supervisor Services and Macro Instructions, GC24-5103 and 0S/VS2 
Supervisor Services and Macro Instructions, GC27-6979, which contains 
information on how to use the services of the supervisor. Among the services 
of the supervisor are program management, task creation and management, 
main storage management, and checkpoint and restart. 

• OS/VS Data Management Macro Instructions, GC26-3793, which contains a 
description of the write sz, link, and return macro instructions, and 
contains the format and contents of the DCB. 



The additional publications referred to in this publication are: 

• 0S/VS1 Storage Estimates, GC24-5094, and 0S/VS2 System Programming 
Library: Storage Estimates, GC28-0604, which contain storage estimates. 

• 0S/VS1 System Data Areas, SY28-0605, which contains a complete description 
of the control blocks used by the operating system. 

• IBM System/370 Principles of Operation, GA22-7000, which contains a 
description of system structure; of the arithmetic, logical, branching, status 
switching, and input/output operations; and of the interruption system. 
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OS/VS Virtual Storage Access Method (VSAM) System Information, GC26-3835, 
which contains information on SMF record types 63 and 67. 

OS/VS Access Method Services, GC35-0009, which contains information on 
generation data groups. 



Notational Conventions 



Bold Type 



Italic Type 



Punctuation 



Brackets 



A uniform system of notation is used to describe the syntax (or format) of utility 
control statements. This notation provides a basis for describing the structure of 
utility control statements. That is, it describes which parameters are required and 
which are optional, the options available in expressing values, and the required 
punctuation. 



In the notation, bold type (list, 0, etc.) is used to indicate specific values that 
can be entered. 



Italic type (nn, user -information, etc.) is used where a number, character string, or 
keyword is to be inserted by the user. For instance, the italic letters in 

MODE=mm 
Tn 



must be replaced by a value when coded. 



The period, comma, equal sign, parentheses, and apostrophe are used for 
punctuation and must be coded as shown. These punctuation marks serve to 
separate the parameters of a utility control statement. 



Brackets ([ ]) indicate that the elements and punctuation they enclose are 
optional. The brackets themselves are for descriptive purposes only, and are not 
to be coded. For instance 

value = element 1 ,element2,element3 [ ,element4] 

indicates that "value=" must be followed by three required parameters 
(element 1, element2, and element3) separated by commas. As indicated by the 
brackets, element4 is optional and need not be coded. If element4 is coded, 
however, the comma that immediately precedes it must also be coded. 

When choices are available for an optional value, the choices appear in brackets, 
one choice above another, as follows: 

value =element0 [,elementl ] 
[,element2 ] 
[,element3 ] 

In the above example, "value=" must be followed by elementO. Optionally, 
element 1, element2, or element3 can be coded. 
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Braces 



Underscoring 



Ellipsis 



KEYWORD=device=list 



Braces ({ }) indicate a required choice. The braces themselves are for descriptive 
purposes only, and are not to be coded. For example: 

value = { element 1 } 
{element2 } 

indicates that "value=" must be followed by either elementl or element2. 



Underscoring indicates a value that is assumed by the program if no value is 
entered for that element. For example, given that no optional value is coded in 
the following: 



value = 



[ elementl ] 
[element2] 



elementl is assumed. 



Ellipsis (...) is used to indicate that one or more additional parameters or sets of 
parameters, each of the same format, optionally can be added to the operand. 
For example, given the following 

value = elementl ,element2... 

the ellipsis indicates that everything preceding the ellipsis and following the equal 
sign can be repeated. 



The term keyword is replace by vol, cvol (vsi only) FROM or TO. 

The term device is replaced by either a generic name, for example, 3330; or a 
substitute for a generic name, for example disk, if this substitute has been 
generated into your system. 

For direct access devices, the term list is replaced by one or more volume serial 
numbers separated by commas. When there is more than one, the entire list field 
must be enclosed in parentheses. 

For tape, the term list is replaced by either one or more volume serial 
number-comma-data set sequence number pairs. Each pair is enclosed in braces 
and separated from the next pair by a comma. When there is more than one pair, 
the entire list field must be enclosed in parentheses. 
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Summary of Major Changes for VS1 Release 3 and VS2 Release 2 



Major Technical Changes 



VS1 Release 3 



VS2 Release 2 



Major Editorial Changes 



• Added device support in IBCDASDI, IEHDASDR, and IEHATLAS for 3330-1 and 
3340 disk storage devices. 

• Added support in IBCDMPRS for 6250 bpi tape units. 

• Added an IEBPTPCH return code of 04. 

• Additional fields in the edited format, partitioned data set directory are included 
in the IEHLIST chapters. 

• Changes have been made, in Appendix A, to the return codes issued by user exit 
routines. 

• A chapter describing a new system utility program (IEHUCAT) has been added to 
this publication. 

• Added restrictions on the use of IEHDASDR utility with password-protected 
VSAM data sets. 



• Incorporated changes as listed in VSl Release 3, with the exception of the 
IEHUCAT chapter which does not run under VS2 Release 2. 

• Added recognition of JES2 control statements to IEBEDIT. 

• IEHLIST for VS2 Release 2 does not support listing catalog entries. It is suggested 
that this entire chapter be carefully reviewed if running under VS2 Release 2. 

• IEHMOVE for VS2 Release 2 does not support moving or copying groups of 
cataloged data sets, catalogs, nor portions of catalogs. Neither can it move nor 
copy the sysctlg data set, ISAM data sets, or VSAM data spaces. Before 
running IEHMOVE under VS2 Release 2, it is suggested that this chapter be 
reviewed in its entirety. 

• IEHPROGM for VS2 Release 2 does not support the following functions: 

1. Building and deleting indexes and their aliases. 

2. Connecting and releasing two volumes. 

3. Building and maintaining generation indexes. 

It does catalog and uncatalog non-VSAM data sets. Before running IEHPROGM 
under VS2 Release 2, it is suggested that this chapter be reviewed in its entirety. 

• IEHDASDR for VS2 Release 2 processed both VSAM and non-VSAM data sets. 
However, additional restrictions are encountered when processing 
password-protected VSAM data sets. 



• Added the syntax and explanation of the label statement of iebupdte. 

• Added a section on dumping and restoring unlike devices to the IEHDASDR 
chapter. 

• Added a data security suggestion to the IEHINITT program. 

• Added an example showing labelling a tape volume at 6250 bpi to the lEHlNlTr 
chapter. 



Summary of Major Changes xxiii 



All syntax presentations have been modified to show the required comma 
between keyword parameters. 

All examples have been adjusted to show exact character punch positions. 

Many notes have been added, to more readily bring to the user's attention any 
special or unusual requirements or restrictions of the individual programs. 

The SMF Type 21 record format in the IFHSTATR chapter has been modified to 
more acdurately reflect the contents of this record. A paragraph on suggested 
use of the information gathered by SMF, and available from record type 21, has 
been added. 

The appendix explaining generation data groups has been removed from this 
publication. The information on generation data groups is now located in 
OS/VS Data Management Services Guide, GC26-3783, and OS/VS Access 
Method Services, GC26-3826. 
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Guide to Utility Program Functions 



Table 1 shows a list of tasks that the utility programs can be used to perform. 
The left-hand column shows tasks that you might want to perform. The middle 
column more specifically defines the tasks. The right-hand column shows the 
utility programs that can be used for each task. Notice that in some cases more 
than one program may be available to perform the same task. 



Table 1. 


Tasks 


and Utility Programs 




Task 








Add 




a password 




Analyze 




tracks on direct access 


IEHATLAS, 


Assign alternate 
tracks 


to a direct access volume 


IEHATLAS, 


Build 




a generation index 
a generation 
an index 




Catalog 




a data set 

a generation data set 




Change 




data set organization 





Compare 

Compress-in- 
place 
Connect 
Construct 

Convert to 
partitioned 

Convert to 
sequential 

Copy 



Create 



Delete 



Dump 

Edit 

Edit and convert 
to partitioned 

Edit and copy 



logical record length 

volume serial number of direct access volume 

a partitioned data set 
sequential data sets 

a partitioned data set 

volumes 

records from mtst and mtdi input 



Utility Program 



IEHPROGM 



IEHDASDR, IBCDASDI 

VS1 ONLY-IEHPROGM 
VS1 ONLY-IEHPROGM 
VS1 ONLY-IEHPROGM 

IEHPROGM 
VS1 ONLY-IEHPROGM 

IEBUPDTE 
IEBGENER 
IEHDASDR 

IEBCOMPR 
IEBCOMPR 

IEBCOPY 

VS1 ONLY-IEHPROGM 

IEBTCRIN 



a sequential data set created as a result of an unload IEBCOPY 

sequential data sets IEBUPDTE, IEBGENER 



a partitioned data set 

an indexed sequential data set 

a catalog 

a direct access volume 

a partitioned data set 

a volume of data sets 

an indexed sequential data set 

cataloged data sets 

dumped data from tape to direct 

job steps 

members 

selected members 

sequential data sets 

to tape 

a library of partitioned members 

a member 

a sequential output data set 

an index 

an output job stream 

a password 

an index structure 

records in a partitioned data set 

a direct access volume 

MTDI input 

a sequential data set 

a job stream 

a sequential data set 



IEBUPDTE, IEBCOPY 
IEBISAM, IEBDG 

VS1 ONLY-IEHMOVE 

IEHDASDR, IBCDMPRS, IEHMOVE 

IEBCOPY, IEHMOVE 

IEHMOVE 

IEBISAM 

VS1 ONLY-IEHMOVE 

access IEHDASDR, IBCDMPRS 

IEBEDIT 

IEBGENER, IEBUPDTE, IEBDG 

IEBCOPY, IEHMOVE 

IEBGENER, IEHMOVE, IEBUPDTE 

IBCDMPRS 

IEBUPDTE 

IEBDG 

IEBDG 

VS1 ONLY-IEHPROGM 

IEBEDIT 

IEHPROGM 

VS1 ONLY-IEHPROGM 

IEBUPDTE 

IEHDASDR, IBCDMPRS 

IEBTCRIN 

IEBGENER, IEBUPDTE 

IEBEDIT 
IEBGENER, IEBUPDTE 
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Task 




Utility Program 


Edit and list 


error statistics by volume (ESV) records 


IFHSTATR 


Edit and print 


a sequential data set 


IEBPTPCH 


Edit and punch 


a sequential data set 


IEBPTPCH 


Enter 


a procedure into a procedure library 


lEBUPDTE 


Exclude 


a partitioned data set member from a copy 
operation 


IEBCOPY, IEHMOVE 


Expand 


a partitioned data set 
a sequential data set 


IEBCOPY 
IEBGENER 


Generate 


test data 


IEBDG 


Get alternate 
tracks 


on a direct access volume lEHDASDR 


, IBCDASDI, lEHATLAS 


Include 


changes to members or sequential data sets 


lEBUPDTE 


Initialize 


a direct access volume 


lEHDASDR, IBCDASDI 


Insert records 


into a partitioned data set 


lEBUPDTE 


Label 


magnetic tape volumes 


IEHINITT 


List 


a password entry 

a volume table of contents 

contents of direct access volume on system output 

device 

number of unused directory blocks and tracks 
partitioned directories 
the contents of the catalog (SYSCTLG 

data set) 


lEHPROGM 
IEHLIST 

lEHDASDR 

IEBCOPY 

IEHLIST 

VSl ONLY-IEHLIST 


Load 


a previously unloaded partitioned data set 

an indexed sequential data set 

an unloaded data set 

UCS and FCB buffers of a 3211 


IEBCOPY 
lEBISAM 

iehmove 
icaprtbl 


Merge 


partitioned data sets 


IEHMOVE, IEBCOPY 


Modify 


a partitioned or sequential data set 


lEBUPDTE 


Move 


a catalog 

a volume of data sets 
cataloged data sets 
partitioned data sets 
sequential data sets 


VSl ONLY-IEHMOVE 
lEHMOVE 

VSl ONLY-IEHMOVE 
IEHMOVE 
IEHMOVE 


Number records 


in a new member 

in a partitioned data set 


lEBUPDTE 
lEBUPDTE 


Password protect 


add a password 
delete a password 
list passwords 
replace a password 


lEHPROGM 
lEHPROGM 
lEHPROGM 
lEHPROGM 


Print 


a sequential data set IEBGENER, 
partitioned data sets 
selected records 


, lEBUPDTE, IEBPTPCH 
IEBPTPCH 
IEBPTPCH 


Punch 


a partitioned data set member 
a sequential data set 
selected records 


IEBPTPCH 
IEBPTPCH 
IEBPTPCH 


Read 


Tape Cartridge Reader input 


IEBTCRIN 


Reblock 


a partitioned data set 
a sequential data set 


IEBCOPY 
IEBGENER, lEBUPDTE 


Recover 


data from defective tracks on direct access 
volumes 


lEHATLAS 


Release 


a connected volume 


VSl ONLY-IEHPROGM 


Rename 


a partitioned data set member 

a sequential or partitioned data set 

moved or copied members 


lEBCOPY, lEHPROGM 

lEHPROGM 

IEHMOVE 


Renumber 


logical records 


lEBUPDTE 


Replace 


a password 

data on an alternate track 

identically named members 

logical records 

members 

records in a member 

records in a partitioned data set 

selected members 

selected members in a move or copy operation 


lEHPROGM 

lEHATLAS 

IEBCOPY 

lEBUPDTE 

lEBUPDTE 

lEBUPDTE 

lEBUPDTE, IEBCOPY 

IEBCOPY 

IEBCOPY, IEHMOVE 
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Task 

Restore 

Scratch 

Uncatlog 
Unload 

Update 

Write 



a dumped direct access volume from tape 

a volume table of contents 
data sets 

data sets 

a partitioned data set 

a sequential data set 

an indexed sequential data set 

a catalog to VS2 Release 2 level 

in place a partitioned data set 

TTR entries in the supervisor call library 

IPL records and a program on a direct access 
volume 



Utility Program 
IBCDMPRS, IEHDASDR 

IEHPROGM 
IEHPROGM 

IEHPROGM 

IEHMOVE, IEBCOPY 

IEHMOVE 

IEBISAM 

VS1 ONLY-IEHUCAT 
IEBUPDTE 
IEHIOSUP 

IBCDASDI, IEHDASDR 
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Introduction 



Control 



OS/VS (Virtual Storage) provides utility programs to assist in organizing and 
maintaining data. Each utility program described in this publication falls into one of 
three classes of programs. The program class into which a utility program falls is 
determined by the function that the utility program performs and the manner in 
which the program is controlled. The program classes are: 

• System utility programs, which are used to maintain system control data at an 
organizational or system level. These programs are controlled by job control 
statements and utility control statements. 

• Data set utility programs, which are used to reorganize, change or compare data 
at the data set and/or record level. These programs are controlled by job control 
statements and utility control statements. 

• Independent utility programs, which are used to prepare devices for system use 
when the operating system is not available. Independent utility programs operate 
outside, and in support of the operating system. These programs are controlled 
by utility control statements. 

The selection of a specific program is dependent on the nature of the job to be 
performed. For example, renaming a data set involves modifying system control 
data. Therefore, a system utility program can be used to rename the data set. In 
some cases, a specific function can be performed by more than one program. Table 
1 in "Guide to Utility Program Functions," which immediately precedes this 
chapter, is provided to help you find the program that performs the function you 
need. 

Note: The IEHDASDR system utility program can be used with volumes containing 
VSAM and/or non-VSAM data sets. The other utility programs which manipulate 
data sets and are contained in this manual cannot be used with VSAM data sets. 
Information about VSAM data sets can be found in OS/VS Access Method 
Services. 



System and data set utility programs are controlled by job control statements and 
utility control statements. Independent utility programs are controlled by utility 
control statements; because these programs are independent of the operating 
system, job control statements are not required. The job control statements and 
utility control statements necessary to use utility programs are provided in the 
major discussion of each utility program. 



Job Control Statements 



A system or data set utility program can be introduced to the operating system in 
different ways: 

• Job control statements can be included in the input stream. 

• Job control statements, placed in a procedure library or defined as an inline 
procedure, can be included by means of the EXEC job control statement. 

• A utility program can be invoked by a calling program. 

If job control statements are placed in a procedure library, they should satisfy the 
requirements for most applications of the program; a procedure, of course, can be 
modified or supplemented for applications that require additional parameters, data 
sets, or devices. The data set utility iebupdte can be used to enter a procedure 
into a procedure library; see "iebupdte Program." 

Independent utility programs do not require job control statements and cannot be 
invoked by a calling program. For information on executing independent utility 
programs, see "Independent Utility Programs" below. 
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A job that modifies a system data set (identified by sysi.) must be run in a single 
job environment; however, a job that uses a system data set, but does not 
modify it, can be run in a multiprogramming environment. The operator should 
be informed of all jobs that modify system data sets. 

DD statements should ensure that the volumes on which the data sets reside 
cannot be shared when update activity is being performed. 

Utility Control Statements 

Utility control statements are used to identify a particular function to be 
performed by a utility program and, when required, to identify specific volumes 
or data sets to be processed. 

The control statements for the utility programs have the following standard 
format: 

label operation operand 

The label symbolically identifies the control statement and, with the exception of 
system utility program IEHINITT, can be omitted. When included, a name must 
begin in the first position of the statement and must be followed by one or more 
blanks. It can contain from one to eight alphameric characters, the first of which 
must be alphabetic. 

The operation identifies the type of control statement. It must be preceded and 
followed by one or more blanks. 

The operand is made up of one or more keyword parameters separated by 
commas. The operand field must be preceded and followed by one or more 
blanks. Commas, parentheses, and blanks can be used only as delimiting 
characters. 

Comments can be written in a utility statement, but they must be separated from 
the last parameter of the operand field by one or more blanks. 

Continuing Utility Control Statements 

Utility control statements are coded on cards or as card images and are contained 
in columns 1 through 71. A statement that exceeds 71 characters must be 
continued on one or more additional cards. A nonblank character must be placed 
in column 72 to indicate continuation. A utility statement can be interrupted 
either in column 71 or after any comma. 

The continued portion of the utility control statement must begin in column 16 
of the following statement. (Job control language continuations can begin in any 
column from 4 through 16, and do not require a nonblank character in column 
72 for continued operand fields.) Comments can be placed on any card 
containing a complete or partial statement. However, when a card is included for 
the sole purpose of continuing a comment, the continuation must begin in column 
16. 

Note: The IEBCOPY, IEBPTPCH, IEBGENER, IEBCOMPR, and IEBDG utility 
programs permit certain exceptions to these requirements (see the applicable 
program description). 

The utility control statements are discussed in detail, as applicable, in the 
remaining chapters. 



Restrictions 



A substitute name that represents two or more different device types (for 
example, DISK, meaning 3330 and 2314) cannot be processed by a utility 
program. 

Unless otherwise indicated in the description of a specific utility program, a 
temporary data set can be processed by a utility program only if the user 
specifies the complete name generated for the data set by the system (for 
example, DSNAME=SYS68296.T000051.RP001.JOBTEMP.TEMPMOD). 
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System Utility Programs 



System utility programs manipulate collections of data and system control 
information. The system utility programs are: 

IEH ATLAS, which is Used to assign alternate tracks when defective tracks are 
indicated. 

IEHDASDR, which is used to initialize direct access volumes or to dump or 
restore data. 

IEHINITT, which is used to write standard labels on tape volumes. 

IEHIOSUP, which is used to update entries in the supervisor call library (VSl 
only). 

IEHLIST, which is used to list system control data. 

IEHMOVE, which is used to move or copy collections of data. 

IEHPROGM, which is used to build and maintain system control data. 

IEHUCAT, which is used to update an OS catalog to the level of a vsam 
catalog (non-VSAM data sets). (VSl only.) 

IFHSTATR, which is used to select, format, and write information about tape 
errors from the IFASMFDP tape or the SYS l. man data set. 

A system utility program is executed or invoked through the use of job control 
statements and utility control statements. 

System utility programs can be executed as jobs or can be invoked as subroutines 
by a calling program. The invocation of utility programs and the linkage 
conventions are discussed in "Appendix B: Invoking Utility Programs from a 
Problem Program." 

When using system utility programs, be sure that: 

• Each data set to be used by programs other than IEHPROGM, IEHMOVE, and 
IEHLIST is defined on a DD statement specifying the data set name. When 
updating activity is being performed by IEHPROGM, IEHMOVE, IEHLIST, or 
IEHDASDR in a multiprogramming environment, other tasks should not be 
allowed to access the data set being updated. (Refer to "Appendix C: dd 
Statements for Defining Mountable Devices" for precautions to be taken.) 

• DD statements defining mountable devices specify that volumes mounted on 
those devices cannot be shared. 

• Mountable volumes are not made available to the system until the user is 
requested by the system to mount the specified volumes. 

• A reader procedure is used that will direct input and output data sets to 
volumes other than those which are to be modified by a system utility 
program. 

• When executing a SCRATCH operation, the data set or volume being scratched 
is not being used by a program executing concurrently. 



Data Set Utility Programs 



Data set utility programs manipulate partitioned, sequential, or indexed sequential 
data sets provided as input to the programs. Data ranging from fields within a 
logical record to entire data sets can be manipulated. The data set utility 
programs are: 

• IEBCOMPR, which is used to compare records in sequential or partitioned data 
sets. 
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• IEBCOPY, which is used to copy, compress, or merge partitioned data sets, to 
select or exclude specified members in a copy operation, and to rename 
and/or replace selected members of partitioned data sets. 

• IEBDG, which is used to create a test data set consisting of patterned data. 

• IEBEDIT, which is used to selectively copy job steps and their associated JOB 
statements. 

• IEBGENER, which is used to copy records from a sequential data set or to 
convert a data set from sequential organization to partitioned organization. 

• IEBISAM, which is used to place source data from an indexed sequential data 
set into a sequential data set in a format suitable for subsequent 
reconstruction. 

• IEBPTPCH, which is used to print or punch records that reside in a sequential 
or partitioned data set. 

• IEBTCRIN, which is used to construct records from the input data stream that 
have been read from the IBM 2495 Tape Cartridge Reader. 

• IEBUPDTE, which is used to incorporate changes to sequential or partitioned 
data sets. 

Data set utility programs can be executed as jobs or can be invoked as 
subroutines by a calling program. The invocation of utility programs and the 
linkage conventions are discussed in "Appendix B: Invoking Utility Programs 
from a Problem Program." 

Independent Utility Programs 

Independent utility programs operate outside, and in support of, the operating 
system. They are not supported, however, by the 3066 console, which is only 
used with the Model 165, System/370. If the 3066 is the only console available, 
execute independent utilities by following step 3b "Executing IBCDASDI and 
IBCDMPRS" below. The independent utility programs are: 

• IBCDASDI, which is used to initialize a direct access volume and to assign 
alternate tracks. 

• IBCDMPRS, which is used to dump and restore the data contents of a direct 
access volume. 

• ICAPRTBL, which is used to load the forms control and Universal Character 
Set buffers of a 3211 after an unsuccessful attempt to IPL, with the 3211 
printer assigned as the output portion of a composite console. 

Executing IBCDASDI and IBCDMPRS 

ibcdasdi and ibcdmprs are loaded as card decks or as card images on tape. 
Control statements for the requested program can follow the last card or card 
image of the program, or can be entered on a separate input device. To execute 

IBCDASDI or IBCDMPRS: 

1. Place the object program deck in the reader or mount the tape reel that 
contains the object program. 

2. Load the object program from the reader or tape drive by setting the load 
selector switches and pressing the console LOAD key. When the program is 
loaded, the wait state is entered and the console lights display the hexadecimal 
value FFFF. 

3. Define the control statement input device in one of the following ways: 

(a) Press the REQUEST key of the console typewriter and, in response to the 
message "DEFINE INPUT device", enter " INPUT =xxxx,cuu". The xxxx is 
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Executing ICAPRTBL 



the device type, c is the channel address, and uu is the unit address. The 
device type can be 1402, 1442 (VSl only), 2400, 2501, or 2540. 

(b) If the console typewriter is not available, enter at storage location 0110 
(hexadecimal): lcuu for a 1442 Card Read Punch; 2cuu for a 2400 
9-track tape unit; or Ocuu for a 2540 Card Read Punch, 2501 card reader, 
3410 tape, or 3420 tape. Press the console interrupt key. 

4. Control statements are printed on the message output device. At the end of 
the job, "END OF JOB" is printed on the message output device, and the 
program enters the wait state. 



ICAPRTBL must be loaded from a card reader. Control statements must follow 
the last card of the program. Only one printer can be initialized each time the 
program is executed. 

To execute ICAPRTBL: 

1. Mount the correct train on the printer and ready the printer. 

2. Place the object program deck and the control cards in the card reader. Ready 
the reader and press the END OF FILE key. 

3. Load the object program from the reader by setting the load selector switches 
and pressing the console LOAD key. 

Wait state codes will be displayed in the address portion of the PSW for normal 
termination and for input/output, system or control card errors. Code B01 is 
issued for normal termination; B02 through B07 are issued for control card errors; 
BOA through B0C are issued for system errors; and Bll through BID are issued for 
input/output errors. Table 1-1 shows these codes and their meanings. 



Table 1-1. icaprtbl Wait-State Codes 



Code Meaning 

B01 Visually check the train 

image printed on the 3211. 

B02 Missing control card or 
control card out of order. 

B03 Incorrect JOB statement. 

B04 Incorrect dfn statement. 

B05 Incorrect ucs statement. 

B06 Incorrect fcb statement. 

B07 Incorrect end statement. 

BOA External interrupt. 

BOB Program check interrupt. 

B0C Machine check interrupt. 

Bll Reader not online. 



Code Meaning 



B12 
B13 



B14 
B15 
B19 
B1A 
BIB 



B1C 
BID 



Reader not ready. 

Reader unit check (display low 

main storage location 2 through 

7 for sense information). 

Reader channel error. 

No device end on reader. 

Printer not online. 

Printer not ready. 

Printer unit check (display low 

main storage location 2 through 

7 for sense information). 

Printer channel error. 

No device end on printer. 
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IBCDASDI Program 

IBCDASDI is an independent utility used to initialize direct access volumes for use 
and to assign alternate tracks on direct access storage volumes. (See 
"Introduction" for general independent utility information.) IBCDASDI jobs can 
be performed continuously by stacking complete sets of control statements. 

Initializing a Direct Access Volume 

IBCDASDI can be used to initialize a direct access volume. A volume can be 
initialized with or without surface analysis, a test for defective tracks; however, a 
surface analysis should be performed when a volume is initialized for the first 
time. 

When a volume is initialized, IBCDASDI: 

• Checks for tracks that have been previously designated as defective (flagged) 
and have had alternates assigned. This test must be suppressed when a disk is 
initialized with surface analysis for the first time. This test must not be 
suppressed when a volume is initialized without surface analysis. 

• Automatically assigns alternates, if necessary, when a volume is initialized with 
surface analysis. Tracks that are available for use as alternates are checked 
first. 

• Writes a track descriptor record (record 0) and erases the remainder of each 
track. When a volume is initialized with surface analysis, IBCDASDI also writes 
a standard home address. 

• Writes IPL records on track (records 1 and 2). 

• Writes volume label on track (record 3) and provides space for additional 
records, if requested. 

• Constructs and writes a volume table of contents (VTOC). 

• Writes an IPL program, if requested. When a volume is initialized with surface 
analysis, the IPL program is written on track for 2305, 2314, or 2319 
volumes. When a volume is initialized without surface analysis, the*IPL 
program is written on track for 2305, 2314, 2319, 3330, 3330-1, or 3340 
volumes. 

Note: Defective tracks are flagged and alternate tracks are assigned when the: 
3330, 3330-1, and 3340 storage volumes are initialized at the factory. An 
IBCDASDI job to initialize a 3330, 3330-1, and 3340 does not perform a surface 
analysis. The "Quick DASDI," which can be performed on a 3330, 3330-1, and 
3340 volume, includes: (1) reading alternate tracks and decreasing the total 
count of the alternates by one when an alternate is found defective or assigned; 
(2) writing a volume label and VTOC; and (3) writing IPLTXT, if requested. 
Record can be rewritten on each track in each case. Note that surface analysis 
is not performed and the home address is not written on the primary tracks. The 
BYPASS and FLAGTEST options of the DADEF statement are ignored. (See 
"DADEF Statement" below.) 

Assigning an Alternate Track 

IBCDASDI can be used to: (1) test a track and, if necessary, assign an alternate 
or (2) bypass testing and automatically assign an alternate. 

If testing is performed, an alternate track is assigned for any track found 
defective. If the defective track is an unassigned alternate, it is flagged to prevent 
its future use. The alternate track address is made known to the operator. 
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Input and Output 



If a track is tested and not found to be defective, no alternate is assigned. The 
operator is notified by a message. 

If testing is bypassed, an alternate track can be assigned for the specified track 
or its alternate, whether it is defective or not. If the specified track is an 
unassigned alternate, it is flagged to prevent its future use. 

Note: No test for defective tracks is performed for 3330, 3330-1, and 3340 
volumes; an alternate track is automatically assigned. 



IBCDASDI uses as input a control data set, which consists of utility control 
statements. 

IBCDASDI produces as output an initialized direct access volume and a message 
data set. 

Control 

IBCDASDI is controlled by utility control statements. Because IBCDASDI is an 
independent utility, operating system job control statements are not used. 

Utility Control Statements 

IBCDASDI utility control statements in the order in which they must appear are: 

JOB statement, which is used to indicate the beginning of an IBCDASDI job. 

MSG statement, which is used to define an output device for operator 
messages. 

dadef statement, which is used to define the volume to be initialized. 

vld statement, which contains information for constructing an initial volume 
label and for allocating space for additional labels. 

VTOCD statement, which contains information for controlling the location of 
the volume table of contents. 

ipltxt statement, which is used to separate utility control statements from 
any IPL program text statements. 

GET alt statement, which is used to assign an alternate track on a volume. 

END statement, which is used to indicate the end of an IBCDASDI job. 

LASTCARD statement, which is used to end a series of stacked IBCDASDI jobs. 



JOB Statement 



MSG Statement 



The JOB statement indicates the beginning of an IBCDASDI job. 
The format of the JOB statement is: 

[label] JOB [user -information] 
JOB must be preceded and followed by at least one blank. 



The MSG statement defines an output device for operator messages. It follows 
the JOB statement and precedes any function definition statements. 



The format of the MSG statement is: 

[label] MSG TODEV=xxxx 
,TOADDR=cuu 
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DADEF Statement 



where: 

TODEV=xxxx 

specifies the type of output device to receive messages, for example, 1403. 
The devices that can be specified are 1403, 1443, 1052, 2400, 3400, 3210, 
and 3211. 

TOADDR=cuu 

specifies the channel number, c, and unit number, uu, of the message output 
device. 



The DADEF statement defines the direct access volume to be initialized. 

The format of the DADEF statement is: 

[label] DADEF TODEV=xxxx 

,TOADDR=cuu 

[,IPL=YES] 

,VOLID= {serial} 

{SCRATCH} 

[,FLAGTEST=NO] 

[,PASSES=n] 

[,BYPASS=YES] 

[,MODEL=n] 

where: 

TODEV=xxxx 

specifies the type of the direct access device to be initialized, for example, 
3330. Note that the 2319 disk is functionally equivalent to the 2314 disk. To 
use a 2319, specify 2314 in the TODEV parameter. To specify the 3330 Model 
11 and the 3333 Model 11, always specify 3330-1 in the TODEV parameter. 

TOADDR=cuu 

specifies channel number, c, and unit number, uu, of the device. 

IPL=YES 

specifies that an IPL program is to be written on the volume. An IPL 
initialization program must be written on a device to be used for system 
residence. If IPL is omitted, no IPL program is written. 

VOLID= 

specifies whether a volume serial number check is to be made. These values 
can be coded: 

serial 

specifies the volume serial number of the volume to be initialized. If serial 
does not match the volume serial number found on the volume to be 
initialized, the operator is notified and the job is terminated. 

SCRATCH 

specifies that no volume serial number check is to be made. 

FLAGTEST=NO 

specifies that no check is to be made for previously flagged tracks on a disk 
volume before surface analysis is performed. FLAGTEST=NO should be 
specified when the disk recording surface is initialized for the first time. 

PASSES=n 

specifies the number of passes per track to be made in checking for defective 
tracks. PASSES is valid when surface analysis is to be performed or when a 
"Quick DASDI" is to be performed on a 3330, 3330-1, or 3340 volume. The 
value n can be through 255. The specification indicates that a "Quick 
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VLD Statement 



VTOCD Statement 



dasdi" is to be performed on a 3330, 3330-1, of 3340 volume. For a 3330, 
3330-1, or 3340 volume, a value other than zero causes record to be written 
on each track. No check is made for defective tracks on a 3330, 3330-1, or 
3340. A specification of 1 through 255 indicates the number of passes to be 
made per track for volumes other than a 3330, 3330-1, or 3340 volume. If 
PASSES is omitted, one pass is made per track. 

BYPASS=YES 

specifies that no check is to be made for defective tracks. If BYPASS is 
omitted, tracks are checked and those found defective are automatically 
assigned alternates. This parameter applies only when surface analysis is not to 
be performed. 

MODEL=n 

specifies a decimal model number (1 or 2). This parameter corresponds to the 
2305-1 and 2305-2, respectively. MODEL is required when a 2305 is to be 
initialized. 



The VLD Statement contains information for constructing an initial Volume label 
and fpr allocating space for additional labels. 

The format of the VLD statement is: 

[label] VLD NEWVOLID=seria/ 



,VOLPASS= {0} 

{1} 
[,OWNERID=xxxxxxxxxx] 
[,ADDLABEL=n] 



where: 



NEWVOLID=ser/a/ 

specifies a one- to six-character volume serial number. 

VOLPASS= 

specifies the value of the volume security bit. These values can be coded: 



specifies that the volume is not security protected. If VOLPASS is omitted, 
is assumed. 



1 



specifies that the volume is security protected. 



OWNERID = xxxxxxxxxx 

specifies a one- to ten-character field that identifies the owner of the volume. 
If OWNERID is omitted, no identification is given. 

ADDLABEL=n 

specifies the total number of additional labels for which space is to be 
allocated. The value of n can be 1 through 7. If ADDLABEL is omitted, is 
assumed. 



The VTOCD statement contains information for controlling the location of the 
volume table of contents (VTOC). 

The format of the VTOCD statement is: 

[label] VTOCD STRTADR=nnnnn 
,EXTENT=nnnn 
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IPLTXT Statement 



GETALT Statement 



where: 

STRTADR=nnnnn 

specifies the one- to five-byte track address, relative to the beginning of the 
volume, at which the VTOC is to begin. The VTOC cannot occupy track or 
any alternate track. 

To improve performance when reading from and writing to the VTOC, it is; 
recommended that every VTOC end on the last track of a cylinder (a cylinder 
boundary). This means that you should determine the starting address for the 
VTOC by subtracting the number of tracks allocated to the VTOC from the 
nearest larger track that ends on a cylinder boundary. For example, if the 
VTOC requires 5 tracks on a 3336 disk pack, which has 19 tracks per cyliner, 
the starting track should be specified as track 14, so that the VTOC will end 
on track 18 (the last track of the first cylinder). 

EXTENT=nnnn 

specifies the length (number of tracks) of the VTOC. 

Table 2-1 shows the number of VTOC entries per track for each device type. 

Table 2-1. vtoc Entries per Track 

Device VTOC Entries per Track 

2314 25 

2319 25 

2305-1 18 

2305-2 34 

3330 39 

3330-1 39 

3340 28 



The IPLTXT statement separates utility control statements from I PL program text 
statements. It is required only when IPL text is included. 

The format of the IPLTXT statement is: 

IPLTXT 

When IPL text is included, END must start in column 2. See "END Statement" 
below. 



The GETALT statement is used to assign an alternate track on a volume. Any 
number of alternate tracks can be assigned in a single job by including a GETALT 
statement for each track. 

Note: A GETALT statement that applies to a 3330, 3330-1, or 3340 device 
causes an alternate track to be assigned automatically without testing. 

The format of the GETALT statement is: 



[label] GETALT 



TODEV=xxxx 

,TOADDR= cuu 

,TRACK=cccchhhh 

,VOLID=sena/ 

[,FLAGTEST=NO] 

[,PASSES=n] 

[,BYPASS=YES] 

[,MODEL=n] 



where: 



TODEV=xxxx 

specifies the device type of the direct access device. 
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END Statement 



LASTCARD Statement 



TOADDR=cuu 

specifies the channel number, c, and unit number, uu, of the direct access 
device. 

TRACK=cccchhhh 

specifies the address of the track for which an alternate is requested, where 
cccc is the cylinder number and hhhh is the head number. 

VOLID=sena/ 

specifies the volume serial number of the volume to which an alternate track is 
to be assigned. If serial does not match the volume serial number found on 
this volume, the operator is notified and the job is terminated. 

FLAGTEST==NO 

specifies that no check is to be made for a previously flagged track before a 
surface analysis for a disk volume is performed on this track. This parameter is 
used when testing before assigning an alternate. 

PASSES=n 

specifies the number of passes, n, to be made when performing a surface 
analysis on this track. The value of n can be 1 through 255. If PASSES is 
omitted, one pass is made. (If, however, the GETALT statement applies to a 
3330 volume, an alternate track is assigned without testing; the PASSES 
parameter is ignored.) This parameter is used when testing before assigning an 
alternate. 

BYPASS=YES 

specifies that no defective-track check is to be made. If BYPASS is omitted, the 
program assigns an alternate only if it finds that the specified track is 
defective. 

MODEL=n 

specifies a decimal model number (1 or 2). This parameter corresponds to the 
2305-1 and 2305-2, respectively. MODEL is required when a 2305 is to be 
initialized. 

The GETALT function should not be used immediately after a RESTORE operation 
that did not complete successfully. Before using get alt in such a case, 
reinitialize the volume, if possible. 



The END statement denotes the end of job. It appears after the last function 
definition statement. 

The format of the END statement is: 

[label] END [user-information] 

END must be preceded and followed by at least one blank. 



The LASTCARD statement is required only when an IBCDASDI job or a series of 
stacked IBCDASDI jobs is followed by other statements on the control statement 
input device. The LASTCARD statement must follow the last END statement 
applying to an IBCDASDI job. 

The format of the LASTCARD statement is: 

LASTCARD 



IBCDASDI Examples 
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The examples that follow illustrate some of the uses of IBCDASDI. Table 2-2 can 
be used as a quick reference guide to IBCDASDI examples. The numbers in the 
"Example" column point to examples that follow. 



Table 2-2. ibcdasdi Example Directory 



IBCDASDI Example 1 



Operation 
Initialize 

Initialize 

Initialize 



Assign alternate 
tracks 



Comments 

A 2305 volume is to be initialized with 
surface analysis. 

A 2305 volume is to be initialized without 
surface analysis. 

A 3330 volume to be used as the system 
residence volume is to be initialized. An IPL 
program is included in TXT format. 

Three alternate tracks are to be assigned 
on a 3330 volume. 



Example 
1 

2 

3 
4 



In this example, a 2305 volume is initialized for the first time. 
A surface analysis is performed with the initialization. 

The example follows: 

INIT JOB 'INITIALIZE 2305' 

MSG TODEV=1403,TOADDR=00E 
DADEF TODEV=2 3 5 , TOADDR= 140, VOLID=SCRATCH , FLAGTEST=NO 

VLD NEWVOLID= 111111 
VTOCD STRTADR=40,EXTENT=8 

END 

The control statements are discussed below: 

• JOB initiates the IBCDASDI job. 

• MSG defines the 1403 on channel 0, unit 0E, as the output message device. 

• dadef specifies that a 2305 volume on channel 1, unit 40, is to be initialized. 
Because the volume is being initialized for the first time, no check is to be 
made for previously flagged tracks. 

• VLD specifies 111111 as the volume serial number of the volume to be 
initialized. 

• VTOCD specifies the starting address and length in tracks of the volume table 
of contents. 



IBCDASDI Example 2 



In this example, a 2305 volume is initialized for the first time. No surface 
analysis is performed with the initialization. 

The example follows: 

INIT JOB INITIALIZE 2305 

MSG TODEV=1403,TOADDR=00E 
DADEF TODEV=2 305 , TOADDR= 1 40 , VOLID=SCRATCH , BYPASS=YES 

VLD NEWVOLID=2 30500 
VTOCD STRTADR=1 ,EXTENT=7 

END 

The control statements are discussed below: 

• DADEF specifies that a 2305 volume is to be initialized and specifies the 
channel and unit number. No check is to be made for the volume serial 
number or for defective tracks. 

• VLD specifies the volume serial number of the volume to be initialized. 

• VTOCD specifies that the volume table of contents is to begin on track 1 and 
is to extend over seven tracks. The VTOC terminates on the last track of the 
first cylinder. 



• end specifies the end of the IBCDASDI job. 
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IBCDASDI Example 3 



In this example, a 3330 volume is initialized for later use as a system residence 
volume. An IPL program is included in standard TXT format. 

The example follows: 

INIT JOB 'INITIALIZE 3330' 

MSG TODEV=1403,TOADDR=00E 
DADEF TODEV=3330 , TOADDR=1 50 , IPL=YES 

VLD NEWVOLID=P1 0000 ,OWNERID=BROWN, ADDLABEL=2 
VTOCD STRTADR-2,EXTENT=7 
IPLTXT 

(IPL program text statements) 

END 

The control statements are discussed below: 

• DADEF specifies that a 3330 volume is to be initialized and specifies the 
channel number and unit number. An IPL program is to be included. 

• VLD specifies a volume serial number and owner identification for the volume 
to be initialized. It also specifies that space is to be allocated for two 
additional labels. 

• VTOCD specifies that the volume table of contents is to begin on track 2 and 
is to extend over nine tracks. 

• IPLTEXT specifies the beginning of IPL program text statements. 

• END specifies the end of IPL program text statements. Because IPL text is 
included, END begins in column 2. 



IBCDASDI Example 4 



In this example, three alternate tracks are assigned to a 3330 volume, without 
reinitialization of the volume. The check for a defective track is bypassed when 
the first two of the three tracks are assigned. 



The example follows: 



ALTRK JOB ASSIGN ALTERNATE TRACKS ON 3330 

MSG TODEV=1052,TOADDR=009 
STMT1 GETALT TODEV=3330 ,TOADDR=1 50 , VOLID=P20000 , 

BYPASS=YES , TRACK=006F000 1 
STMT2 GETALT TODEV=3330 ,TOADDR=1 50 , VOLID=P20000 , 

BYPASS=YES , TRACK-009 1 0004 
STMT3 GETALT TODEV=3330,TOADDR=1 50, 

TRACK=004B0007 , VOLID=P20000 
END 

The control statements are discussed below: 

• The first and second GETALT statements bypass the check for defective 
tracks. 

• The third GETALT statement causes the check for a defective track to be 
made because BYPASS is not included. 



72 

C 
C 
C 
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IBCDMPRS Program 



Input and Output 



Control 



IBCDMPRS is an independent utility used to dump and restore data on direct 
access volumes. (See "Introduction" for general independent utility information.) 

The data contents of a direct access volume (all data except the home address) 
can be dumped to 2314, 3330, 3330-1, 3340, or tape volumes and restored to a 
direct access volume that resides on the same type of device as the source 
volume. Both the source volume and the volume to which data is to be restored 
must have been initialized according to operating system specifications. 
IBCDMPRS is useful for preparing transportable copies and backup copies of 
direct access volumes. 



IBCDMPRS uses as input: 

• A control data set, which contains utility control statements. 

• A data set to be dumped to tape or to be restored to a direct access volume. 
IBCDMPRS produces as output: 

• A data set dumped to tape or a data set restored to a direct access volume. 

• A message data set. 



IBCDMPRS is controlled by utility control statements. Because IBCDMPRS is an 
independent utility, operating system job control statements are not used. 



Utility Control Statements 

IBCDMPRS utility control statements are: 

• JOB statement, which is used to begin an IBCDMPRS job. 

• MSG statement, which is used to define an output device for operator 
messages. 

• DUMP statement, which is used to identify the volume to be dumped and the 
receiving volume. 

• VDRL statement, which is used to specify the upper and lower track limits of a 
partial dump. 

• RESTORE statement, which is used to identify the source volume whose data is 
to be restored and the receiving volume. 

• END statement, which is used to indicate the end of an IBCDMPRS job. 



JOB Statement 



MSG Statement 



The JOB statement indicates the beginning of a job. 
The format of the JOB statement is: 

[label] JOB [user-information] 
JOB must be preceded and followed by at least one blank. 



The MSG statement defines an output device for operator messages. It follows 
the JOB statement and precedes any function definition statements. 
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DUMP Statement 



The format of the MSG statement is: 

[label] MSG TODEV=xxxx 
,TOADDR=cuu 

where: 

TODEV=xxxx 

specifies the type of the output device to receive messages, for example, 1403. 
The devices that can be specified are 1403, 1443, 1052, 2400, 3400, 3210, 
and 3211. 

TOADDR= cuu 

specifies the channel number, c, and unit number, uu, of the message output 
device. 



The DUMP statement is used to identify both the source volume whose contents 
are to be dumped and the receiving volume. The data contents of the entire 
source volume are dumped, including any data on alternate tracks. If both the 
source and receiving volumes reside on 2314, 2319, 3330, 3330-1, or 3340 
volumes, the receiving volume is an exact replica of the source volume. 

The format of the DUMP statement is: 



[label] DUMP 



FROMDEV=xxxx 

,FROMADDR=cuu 

,TODEV=xxxx 

,TOADDR=cuu 

[, VOLID = sen"a/[,ser/a/]] 

[,MODE=mm] 

[,MODEL=n] 



where: 



FROMDEV=xxxx 

specifies the type of the source device, for example, 3330. 

FROMADDR= cuu 

specifies channel number, c, and unit number, uu, of the source device. 

TODEV=xxxx 

specifies the type of the receiving device, for example, 2400. If the receiving 
device is a tape unit and no MODE parameter is specified, the data is written at 
the highest density supported by the device. (For 7-track tape, the default 
mode is 93.) 

TO ADDR= cuu 

specifies the channel number, c, and unit number, uu, of the receiving device. 

VOLID = seria/[,ser/a/] .. . 

specifies the volume serial numbers of the receiving volumes to which data is 
to be dumped. VOLID is required when the receiving volume has been 
initialized according to operating system specifications. If serial does not match 
the volume serial number found on the receiving volume, the operator is 
notified and the job is terminated. If VOLID is not specified and the receiving 
volume contains a volume serial number, the operator is notified. 



3-2 OS/VS Utilities 



VDRL Statement 



MODE=mm 

specifies the bit density for data written onto the receiving magnetic tape 
volume. This parameter is applicable to 7-track tape units and to 9-track tape 
units with density selections of 800, 1600, and 6250 bits per inch. Valid 
modes for 7-track tape are shown in Table 3-1. (Only those modes that set 
the data converter on are accepted.) For 9-track tape with density selections 
of 800, 1600, and 6250 bits per inch, the mode settings are CB, C3, and D3, 
respectively. If the receiving device is not a tape unit, the MODE parameter is 
ignored. If the receiving device is a tape drive but no mode is specified, the 
data is written at the highest density supported by the device. 

MODEL=n 

specifies a decimal model number (1 or 2) for a 2305. This parameter is 
applicable only when a 2305 is specified. If MODEL is omitted, 2305-1 is 
assumed. 

Note: The 2319 disk is functionally equivalent to the 2314 disk. To use the 
2319, specify 2314. The 3330 and 3333 Model 1 devices are functionally 
equivalent. To use either device, specify 3330. The 3330 Model 11 and the 3333 
Model 11 are also functionally equivalent. To use either of these devices, specify 
3330-1. 

Dump time can be minimized by selecting devices assigned to different channels. 
For example: 

DUMP FROMDEV=3330,FROMADDR= 1 50,TODEV=2400,TOADDR=282 

Table 3-1 shows valid modes for 7-track tape that can be entered for the MODE 
parameter. 



Table 


3-1. Valid 7-Track Tape Unit Modes 


in IBCDMPRS 




Mode 
(mm) 


Density 
(bits per inch) 


Translator 


Data 
Converter 


Parity 


13 


200 


Off 


On 


Odd 


53 


556 


Off 


On 


Odd 


93 


800 


Off 


On 


Odd 



The VDRL (volume dump/restore limits) statement is used to specify the upper 
and lower limits of a partial dump. If a track within these limits has had an 
alternate assigned to it, the data on the alternate track is included in the dump. 
When the VDRL statement is used, it must be preceded by a DUMP statement 
and must be followed by an END statement. 

The format of the VDRL statement is: 

[label] VDRL BEGIN =nnnnn 
[,END= nnnnn] 

where: 

BEGIN = nnnnn 

specifies a one- to five-byte relative track address that identifies the first track 
to be dumped. 

END = nnnnn 

specifies the relative trick address of the last track to be dumped. If only one 
track is to be dumped, this address is the same as the beginning address. If 
END is omitted, the last track of the volume, excluding those tracks reserved as 
alternates, is assumed to be the upper limit. 
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RESTORE Statement 



END Statement 



The RESTORE statement is used to identify both the source volume whose data 
contents are to be restored and the receiving volume. 

Note: IBCDMPRS can be used to restore a tape created by IEHDASDR. 
Conversely, IEHDASDR can be used to restore a tape created by IBCDMPRS. 

The format of the RESTORE statement is: 

[label] RESTORE FROMDEV=xxxx 
,FROMADDR= cuu 
,TODEV=xxxx 
,TOADDR= cuu 
,VOLID =ser/a/ 
[,MODE= mm] 
[,MODEL=n] 
where: 

FROMDEV=xxxx 

specifies the type of the source device, for example, 2400. 

FROMADDR=cuu 

specifies the channel number, c, and unit number, uu, of the source device. 

TODEV=xxxx 

specifies the type of the receiving device, for example, 3330. This device type 
must be the same as the device containing the volume originally dumped. 

TO ADDR= cuu 

specifies the channel number, c, and unit number, uu, of the receiving device. 

VOLID=sena/ 

specifies the volume serial number of the receiving volume. If serial does not 
match the volume serial number found on the receiving volume, the operator is 
notified and the job is terminated. 

MODE=mm 

specifies the bit density for data written to the receiving tape volume. This 
parameter must match the mode specified when data was written to the source 
volume. MODE should not be specified if the source and receiving volumes are 
not tape or if MODE was not specified when data was written to the source 
volume. Valid modes are shown earlier in Table 3-1. (Only those modes that 
set the data converter on are accepted.) For 9-track tape units with density 
selections of 800, 1600, and 6250 bits per inch, the mode settings are CB, C3, 
and D3, respectively. 

MODEL=n 

specifies a decimal model number (1 or 2) for a 2305. If MODEL is omitted, 
2305-1 is assumed. 

Restore time can be minimized by selecting devices assigned to different 
channels. For example: 

RESTORE FROMDEV=2400,FROMADDR=282,TODEV=3330,TOADDR= 1 50 



The END statement marks the end of job. It appears after the last function 
definition statement. 

The format of the END statement is: 

[label] END [user-information] 

END must be preceded and followed by at least one blank. 
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IBCDMPRS Examples 



The examples that follow illustrate some of the uses of IBCDMPRS. Table 3-2 can 
be used as a quick reference guide to the examples. The numbers in the 
"Example" column point to examples that follow. 



Table 3-2. IBCDMPRS Example Directory 

Operation Comments 

DUMP A direct access volume is to be 

dumped to a tape volume. 

RESTORE A data set dumped to tape is to be 

restored to a direct access volume. 



Example 
1 

2 



IBCDMPRS Example 1 



In this example a direct access volume is dumped to a tape volume. 
The example follows: 



72 



DUMP 



END 



JOB DUMP 3330 ONTO TAPE 
MSG TODE V= 3210, TOADDR= 009 
DUMP FROMDEV=3330,FROMADDR=150, 
TODEV=2400 , TOADDR=280 



IBCDMPRS Example 2 



In this example, dumped data is restored to a direct access volume. 
The example follows: 

RESTORE JOB RESTORE 3330 FROM TAPE 
MSG TODE V=3210,.TOADDR= 009 
RESTORE FROMDEV=2400 , FROMADDR=280 , TODEV=3330 , 
TOADDR=150,VOLID=PZ1 1 1 1 
END 



72 
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ICAPRTBL Program 



Input and Output 



Control 



ICAPRTBL is an independent utility used to load the Universal Character Set 
(ucs) buffer and the forms control buffer (FCB) for an IBM 3211 Printer. (See 
"Introduction" for general independent utility information.) 

ICAPRTBL is used when the 3211 is assigned as the output portion of a 
composite console and an unsuccessful attempt has been made to initialize the 
operating system because the UCS and FCB buffers contain improper bit patterns. 
ICAPRTBL is used to properly load the buffers so the operating system can be 
initialized. 

Note: When an operable console printer keyboard is available, the buffers are 
loaded under the control of the operating system. 



ICAPRTBL uses as input utility control statements that contain images to be 
loaded into the Universal Character Set and/or forms control buffer. ICAPRTBL 
produces as output properly loaded UCS and FCB buffers. 



ICAPRTBL i$ controlled by utility control statements. Because ICAPRTBL is an 
independent utility, operating system job control statements are not used. 



Utility Control Statements 

ICAPRTBL utility control statements are: 

• JOB statement, which is used to indicate the beginning of an ICAPRTBL job. 

• DFN statement, which is used to define the address of the 3211. 

• UCS statement, which contains an image of the characters to be loaded into 
the UCS buffer. 

• FCB statement, which defines the image to be loaded into the FCB. 

• END statement, which is used to indicate the end of an ICAPRTBL job. 

The JOB statement indicates the beginning of an ICAPRTBL job. 
The format of the JOB statement is: 

[label] JOB [user -information] 
JOB must be preceded and followed by at least one blank. 



JOB Statement 



DFN Statement 



The DFN statement is used to define the address of the 3211 and to specify that 
lowercase letters are to be printed in uppercase when the lowercase print train is 
not available. 

The format of the DFN statement is: 

DFN ADDR=cuu f FOLD = {Y } 

IN } 
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UCS Statement 



FCB Statement 



where: 

ADDR=cuu 

specifies the channel number, c, and unit number, uu, of the 3211. 

FOLD= 

specifies whether lowercase letters are to be printed as uppercase letters when 
the lowercase print train is not available. These values can be coded: 

Y 

specifies that lowercase letters are to be printed as uppercase letters when 
the lowercase print train is not available. 



N 



specifies that lowercase letters are not to be printed as uppercase letters. 



The UCS statement contains an image to be loaded into the UCS buffer. 

The format of the UCS statement is: 

[ucsname] UCS ucs- image 

where: 

ucsname 

is a one- to eight-character alphameric name. This name is printed on the 
printer to serve as a reference to the print train being used. 

ucs -image 

specifies characters to be loaded into the UCS buffer. The characters must be 
contained in columns 16 through 71. The first UCS statement contains the first 
56 characters; subsequent statements contain continuations of the image to be 
loaded into the UCS buffer. 



The FCB statement defines the image to be loaded into the forms control buffer. 
The FCB statement may precede or follow the UCS statement. 

The format of the FCB statement is: 



[fcbname] FCB 



LPI={6} 

{8} 
,LNCH=((/,c)[,(/,c,)...]) 
,FORMEND=x 



where: 



fcbname 

specifies a one- to eight-character name of the image loaded into the forms 
control buffer. The actual image loaded into the buffer is not affected by this 
name, but to serve as a meaningful reference when printed on the printer, 
fcbname should be the same as the FCB image being used. 



LPI= 



specifies the number of lines per inch that will be printed on the document. 
These values can be coded: 



specifies that six lines per inch will be printed. 



specifies that eight lines per inch will be printed. 
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END Statement 



ICAPRTBL Example 



LNCH= 

specifies the channels of the FCB image. Each set of parentheses must contain 
the line number (1-180), a comma, and the channel number (1-12) to be 
assigned to that line. One or all of the 12 channels may be assigned in any 
order. Each set must be separated by commas and the entire group surrounded 
by parentheses. 

FORMEND=x 

specifies the number of lines (maximum 180) on the printer form. For an 11 
inch form, spacing six lines per inch, x must be 66. 



The END statement signals the end of the ICABPRTBL job. 
The format of the END statement is: 

[label] END [user-information] 
END must be preceded and followed by at least one blank. 



In this example, an All UCS image and an FCB image are loaded into the UCS 
and FCB buffers. 



A11 



The example follows: 

JOB LOAD A1 1 IMAGE 
DFN ADDR=002,FOLD=N 
UCS 



STD2 FCB 



END 



72 



1 < . =IHGFEDCBA*$-RQPONMLKJ% , £ZYXWVUTS/3#0987£5432 1 < . =IHGF 
EDCBA*$-RQPONMLKJ%,£ZYXWVUTS/a#098765432K.=IHGFEDCBA*$- 
RQPONMLKJ% , &ZYXWVUTS/a#098765432 1 < . =IHGFEDCBA*$-RQPONMLK 
J%, 6ZYXWVUTS/a#098765432K.=IHGFEDCBA*$-RQPONMLKJJS, SZYXW 
VUTS/a#098765432K.=IHGFEDCBA*$-RQPONMLKJJJ # &ZYXWVUTS/3#0 
98765432 K.=IHGFEDCBA*$-RQPONMLKJX, SZYXWVUTS/2309876543 2 
K.=IHGFEDCBA*$-RQPONMLKJK, 6ZYXWVUTS/3#098765432K.=IHGF 
EDCBA*$-RQPONMLKJ%, SZYXWVUTS/a#098765432 

LPI=6, C 

LNCH=( (4,1), (10,2), (16,3), (22,4), ( 28 , 5 ) , ( 34 , 6 ) , ( 40 , 7 ) , C 

(46, 8), (52, 10), (58, 11 ) , ( 64, 1 2 ) , ( 66,9 ) ) 

The control statements are discussed below: 

• DFN specifies the channel and unit number of the 3211 and specifies that 
lowercase letters are not to be printed as uppercase letters when the lowercase 
print train is not available. 

• UCS specifies the characters to be loaded into the UCS buffer. 

• FCB specifies the values to be loaded into the forms control buffer. 
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IEBCOMPR Program 



IEBCOMPR is a data set utility used to compare two sequentially organized or two 
partitioned data sets at the logical record level to verify a backup copy. Fixed, 
variable, or undefined records from blocked or unblocked data sets or members 
can be compared. (See "Introduction" for general data set utility information.) 

Two sequential data sets are considered equal, that is, are considered to be 
identical, if: 

• The data sets contain the same number of records. 

• Corresponding records and keys are identical. 

If these conditions are not met, an unequal comparison results. If records are: 
unequal, the record and block numbers, the names of the DD statements thai; 
define the data sets, and the unequal records are listed in a message data set. 
Ten successive unequal comparisons terminate the job step unless a user routine 
is provided to handle error conditions. 

Two partitioned data sets are considered equal if: 

• Corresponding members contain the same number of records. 

• Note lists are in the same position within corresponding members. 

• Corresponding records and keys are identical. 

If these conditions are not met, an unequal comparison results. If records are 
unequal, the record and block numbers, the names of the DD statements that 
define the data sets, and the unequal records are listed in a message data set 
After ten successive unequal comparisons, processing continues with the next 
member unless a user routine is provided to handle error conditions. 

Partitioned data sets can be compared only if all the names in one or both of the 
directories have counterpart entries in the other directory. The comparison is 
made on members identified by these entries and corresponding user data. 

Figure 5-1 shows the directories of two partitioned data sets. Directory 2 
contains corresponding entries for all the names in Directory 1; therefore, the 
data sets can be compared. 




Directory 1 

A B C D G L 




Figure 5-1. Partitioned Directories Whose Data Sets Can Be Compared Using 

IEBCOMPR 

Figure 5-2 shows the directories of two partitioned data sets. Each directory 
contains a name that has no corresponding entry in the other directory; 
therefore, the data sets cannot be compared, and the job step is terminated. 
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Directory 1 

A Bfc F H I J 



Figure 5-2. 




Partitioned Directories Whose Data Sets Cannot Be Compared Using 

IEBCOMPR 



User exits are provided for optional user routines to process user labels, handle 
error conditions, and modify source records. See "Appendix A: Exit Routine 
Linkage" for a discussion of the linkage conventions to be followed when user 
routines are used. 

At the completion or termination of IEBCOMPR, the highest return code 
encountered within the program is passed to the calling program. 



Input and Output 



IEBCOMPR uses the following input: 

• Two sequential or two partitioned data sets to be compared. 

• A control data set that contains utility control statements. This data set is 
required if the input data sets are partitioned or if user routines are used. 

IEBCOMPR produces as output a message data set that contains informational 
messages (for example, the contents of utility control statements), the results of 
comparisons, and error messages. 

IEBCOMPR provides a return code to indicate the results of program execution. 
The return codes and their meanings are: 

• 00, which indicates successful completion. 

• 08, which indicates an unequal comparison. Processing continues. 

• 12, which indicates an unrecoverable error. The job step is terminated. 

• 16, which indicates that a user routine passed a return code of 16 to 
IEBCOMPR. The job step is terminated. 



Control 



IEBCOMPR is controlled by job control statements and utility control statements. 
The job control statements are required to execute or invoke IEBCOMPR and to 
define the data sets that are used and produced by IEBCOMPR. The utility control 
statements are used to indicate the input data set organization (that is, sequential 
or partitioned), to identify any user routines that may be provided, and to 
indicate whether user labels are to be treated as data. 



5-2 OS/VS Utilities 



Job Control Statements 

Table 5-1 shows the job control statements necessary for using IEBCOMPR. 

Table 5-1. iebcompr Job Control Statements 

Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (PGM=iebcompr> or, if the job control 

statements reside in a procedure library, the procedure name. 

SYSPRINT DD Defines a sequential message data set, which can be written to a system 
output device, a tape volume, or a direct access volume. 

SYSUT1 DD Defines an input data set to be compared. 

SYSUT2 DD Defines an input data set to be compared. 

SYSIN DD Defines the control data set or specifies DUMMY if the input data sets are 

sequential and no user routines are provided. The control data set normally 
resides in the input stream; however, it can be defined as a member within a 
library of partitioned members. 



One or both of the input data sets can be passed from a preceding job step. 

Input data sets residing on different device types can be compared. Input data 
sets with a sequential organization written at different densities can be compared. 



Restrictions 



• The SYSPRINT DD statement must be present for each use of IEBCOMPR. 
•. The SYSIN DD statement is required. 

• The logical record lengths of the input data sets must be identical; otherwise, 
unequal comparisons result. The block sizes of the input data sets can differ; 
however, block sizes must be multiples of the logical record length. 

• The block size specified in the SYSPRINT DD statement must be a multiple of 
121. The block size specified in the SYSIN DD statement must be a multiple of 
80. 

Utility Control Statements 

The utility control statements used to control IEBCOMPR are: 

• COMPARE statement, which is used to indicate the organization of a data set. 

• EXITS statement, which is used to identify user exit routines to be used. 

• LABELS statement, which is used to indicate whether user labels are to be 
treated as data by IEBCOMPR. 



COMPARE Statement 



The COMPARE statement is used to indicate the organization of data sets to be 
compared. 

The format of the COMPARE statement is: 

[label] COMPARE TYPORG= {PS} 

{PO} 

where: 

TYPORG= 

specifies the organization of the input data sets. If TYPORG is omitted, input 
data sets are assumed to be sequentially organized. The values that can be 
coded are: 
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PS 



EXITS Statement 



LABELS Statement 



specifies that the input data sets are sequential data sets. If TYPORG is not 
specified, PS is assumed. 

PO 

specifies that the input data sets are partitioned data sets. 

The COMPARE statement, if included, must be the first utility control statement. 
COMPARE is required if the EXITS or LABELS statement is used or if the input 
data sets are partitioned data sets. 



The EXITS statement is used to identify any user exit routines to be used. 

The format of the EXITS statement is: 

[label] EXITS [INHDR =routinename] 
[,INTLR= routinename] 
[, ERROR = routinename] 
[,PRECOMP= routinename] 

where: 

INHDR = routinename 

specifies the symbolic name of a routine that processes user input header 
labels. 

INTLR= routinename 

specifies the symbolic name of a routine that processes user input trailer 
labels. 

ERROR = routinename 

specifies the symbolic name of a routine that is to receive control after each 
unequal comparison for error handling. If this parameter is omitted and ten 
consecutive unequal comparisons occur while IEBCOMPR is comparing 
sequential data sets, processing is terminated; if the input data sets are 
partitioned, processing continues with the next member. 

PRECOMP= rout inename 

specifies the symbolic name of a routine that processes logical records 
(physical blocks in the case of VS or VBS records longer than 32K bytes) from 
either or both of the input data sets before they are compared. 

The EXITS statement is required if a user exit routine is to be used. If more than 
one valid EXITS statement is included, all but the last EXITS statement are 
ignored. For a discussion of the processing of user labels as data set descriptors, 
see "Appendix D: Processing User Labels." 



The LABELS statement specifies whether user labels are to be treated as data by 
IEBCOMPR. For a discussion of this option, refer to "Processing User Labels as 
Data" in "Appendix D: Processing User Labels." 

The format of the LABELS statement is: 



[label] LABELS [DATA= 



{ YES } 
{NO} 
{ALL} 
{ONLY}] 
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IEBCOMPR Examples 



IEBCOMPR Example 1 



where: 

DATA= 

specifies whether user labels are to be treated as data. The values that can be 
coded are: 

YES 

specifies that any user labels that are not rejected by a user's label 
processing routine are to be treated as data. Processing of labels as data 
stops in compliance with standard return codes. If no value is entered, YES 
is assumed. 



NO 



specifies that user labels are not to be treated as data. 

ALL 

specifies that user labels are to be treated as data regardless of any return 
code. A return code of 16 causes IEBCOMPR to complete processing of the 
remainder of the group of user labels and to terminate the job step. 

ONLY 

specifies that only user header labels are to be treated as data. User header 
labels are processed as data regardless of any return code. The job 
terminates upon return from the OPEN routine. 

Note: LABELS DATA=NO must be specified to make standard user label (SUL) 
exits inactive when input/output data sets with nonstandard labels (NSL) are to 
be processed. 

If more than one valid LABELS statement is included, all but the last LABELS 
statement are ignored. 



The examples that follow illustrate some of the uses of IEBCOMPR. Table 5-2 can 
be used as a quick reference guide to IEBCOMPR examples. The numbers in the 
"Example" column point to examples that follow. 



Table 5-2. 

Operation 
COMPARE 
COMPARE 
COMPARE 

COMPARE 

COMPARE 

COPY (using 
IEBCOPY) 
and COMPARE 

COPY (using 
IEBCOPY) and 
COMPARE 



iebcompr Example Directory 

Data Set 
Organization 

Sequential 



Sequential 
Sequential 

Sequential 

Partitioned 
Sequential 

Partitioned 



Devices Comments Example 

9-track Tape No user routines. Blocked input. 1 

7-track Tape No user routines. Blocked input. 2 

7-track and User routines. Blocked input. 
9-track Tape Different density tapes. 3 

Card Reader, No user routines. Blocked input. 
9-track Tape 4 

2314 Disk No user routines. Blocked input. 5 

9-track Tape No user routines. Blocked input. 
Two job steps; data sets are 
passed to second job step. 6 

2314 Disk User routine. Blocked input. 
Two job steps; data sets are 
passed to second job step. 7 



In this example, two sequential data sets that reside on 9-track tape 
volumes are to be compared. 
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IEBCOMPR Example 2 



The example follows: 

//TAPETAPE JOB 09#660, SMITH 

// EXEC PGM= IEBCOMPR 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD UNIT=2400,LABEL=( , NL ) , 

// DCB=(RECFM=FB,LRECL=80,BLKSIZE=2000 ), 

// DISP=( OLD , KEEP ) , VOI.UME=SER=00 1 234 

//SYSUT2 DD UNIT=2400,LABEL=( ,NL),DISP=( OLD, KEEP), 

// DCB=(RECFM=FB,LRECL-80,BLKSIZE=1040 ), 

// VOLUME=SER=001235 

//SYSIN DD DUMMY 

/* 

Because no user routines are to be used and the input data sets have a sequential 
organization, utility control statements are not used. 

The control statements are discussed below: 

• SYSUT1 DD defines an input data set, which resides on an unlabeled, 9-track 
tape volume. The blocked data set was originally written at a density of 800 
bits per inch. 

• SYSUT2 DD defines an input data set, which resides on an unlabeled, 9-track 
tape volume. The blocked data set was originally written at a density of 800 
bits per inch. 

• SYSIN DD defines a dummy data set. 



In this example, two sequential data sets that reside on 7 -track tape volumes are 
to be compared. 

The example follows: 

//TAPETAPE JOB 09#660, SMITH 

// EXEC PGM=IEBCOMPR 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=SET1 ,LABEL=( 2 ,SUL) ,DISP=( OLD,KEEP ) , 

// VOL=SER-00 1234, DCB=( DEN=2 , RECFM=FB , LRECL=80 , 

// BLKSIZE=2000,TRTCH=C),UNIT=2400 

//SYSUT2 DD DSNAME=SET1 ,LABEL=( , SUL ), DISP=( OLD, KEEP ) , 

// VOL=SER=00 1235, DCB=( DEN=2 , RECFM=FB , LRECL=80 , 

// BLKSIZE=2000 , TRTCH=C ) , UNIT=2400 

//SYSIN DD * 

COMPARE TYPORG=PS 
LABELS DATA=ONLY 
/* 

The control statements are discussed below: 

• SYSUTi DD defines an input data set, which resides on a labeled, 7-track tape 
volume. The blocked data set was originally written at a density of 800 bits 
per inch with the data converter on. 

• SYSUT2 DD defines an input data set, which is the first or only data set on a 
labeled, 7-track tape volume. The blocked data set was originally written at a 
density of 800 bits per inch with the data converter on. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• COMPARE specifies that the input data sets are sequentially organized. 

• LABELS specifies that only user header labels are to be compared. 
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IEBCOMPR Example 3 



IEBCOMPR Example 4 



In this example, two sequential data sets written at different densities on 
different device types are to be compared. 

The example follows: 

//TAPETAPE JOB 09 #660, SMITH 

// EXEC PGM=IEBCOMPR 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=SET1 ,LABEL=( ,SUL),DI SP=( OLD, KEEP), 

// VOL=SER=001234,DCB=(DEN=1 ,RECFM=FB, LRECL=80 , 

// BLKSIZE=320,TRTCH=C),UNIT=2400 

//SYSUT2 DD DSNAME=SET2,LABEL=( ,SUL),DI SP=( OLD, KEEP), 

// DCB=( RECFM=FB , LRECL=80 , BLKSIZE=640 ) , UNIT=2400 , 

// VOLUME=SER=001235 

//SYS IN DD * 

COMPARE TYPORG=PS 

EXITS INHDR=HDRS , INTLR=TLRS 
LABELS DATA=NO 
/* 

The control statements are discussed below: 

• SYSUTl DD defines an input data set, which is the first or only data set on a 
labeled, 7-track tape volume. The blocked data set was originally written at a 
density of 556 bits per inch with the data converter on. 

• SYSUT2 DD defines an input data set, which is the first or only data set on a 
labeled, 9-track tape volume. The blocked data set was originally written at a 
density of 800 bits per inch. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• COMPARE specifies that the input data sets are sequentially organized. 

• exits identifies the names of routines to be used to process user input header 
labels and trailer labels. 

• LABELS specifies that the user input header and trailer labels are not to be 
compared. 



In this example, two sequential data sets (card input and tape input) are to be: 
compared. 

The example follows: 

//CARDTAPE JOB 09#660, SMITH 

// EXEC PGM= IEBCOMPR 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD DUMMY 

//SYSUT2 DD UNIT=2400,VOLUME=SER=001234,LABEL=( ,NL), 

// DCB=(RECFM=FB,LRECL=80,BLKSIZE=2000 ) ,DISP=( OLD, KEEP ) 

//SYSUT1 DD DATA 

(input card data set) 

/* 

The control statements are discussed below: 

• SYSIN DD defines a dummy control data set. Because no user routines are 
provided and the input data sets are sequential, utility control statements are 
not used. 

• SYSUT2 DD defines an input data set, which resides on an unlabeled, 9-track 
tape volume. The blocked data set was originally written at a density of 800 
bits per inch. 
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IEBCOMPR Example 5 



• SYSUTl DD defines an input data set (card input). 

In this example, two partitioned data sets are to be compared. 

The example follows: 

//DISKDISK JOB 09#660, SMITH 

// EXEC PGM= IEBCOMPR 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=PDSSET,UNIT=2314,DISP=SHR, 

// DCB=(RECFM=FB,LRECL=80,BLKSIZE=2000 ), 

// VOLUME=SER=1 11112 

//SYSUT2 DD DSNAME=PDSSET,UNIT=2314,DISP=SHR, 

// DCB=(RECFM=FB,LRECL=80,BLKSIZE=2000 ), 

// VOLUME=SER=1 11113 

//SYSIN DD * 

COMPARE TYPORG=PO 
/* 

The control statements are discussed below: 

• SYSUTl DD defines an input partitioned data set. The blocked data set resides 
on a 2314 volume. 

• SYSUT2 DD defines an input partitioned data set. The blocked data set resides 
on a 2314 volume. 

• SYSIN DD defines the control data set, which follows in the input stream. The 
data set consists of one utility control statement. 



IEBCOMPR Example 6 



In this example, a sequential data set is to be copied and compared in two job 
steps. 

The example follows: 

//TAPETAPE JOB 09#660, SMITH 

//STEPA EXEC PGM=IEBGENER 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSN=COPYSET f UNIT=2400,DISP=( OLD, PASS), 

// DCB=(RECFM=FB,LRECL=80,BLKSIZE=640 ),LABEL=( , SL) , 

// VOLUME=SER=001234 

//SYSUT2 DD DSNAME=COPYSET , DISP=( , PASS ) , LABEL=( , SL ) , 

// DCB=( RECFM=FB , LRECL=80 , BLKSIZE=640 ) , UNIT=2400 , 

// VOLUME=SER=001235 

//SYSIN DD DUMMY 

/* 

//STEPB EXEC PGM= IEBCOMPR 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=*. STEPA. SYSUT1 ,DISP=(OLD, KEEP) 

//SYSUT2 DD DSNAME=*. STEPA. SYSUT2 ,DISP=( OLD, KEEP) 

//SYSIN DD DUMMY 

/* 

The first job step copies the data set and passes the original and copied data sets 
to the second job step. The second job step compares the two data sets. 

The control statements for the IEBCOMPR job step are discussed below: 

• SYSUTl DD defines an input data set passed from the preceding job step. The 
data set resides on a labeled, 9-track tape volume. The blocked data set was 
originally written at a density of 800 bits per inch. 

• SYSUT2 DD defines an input data set passed from the preceding job step. The 
data set, which was created in the preceding job step, resides on a labeled, 
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IEBCOMPR Example 7 



9-track tape volume. The blocked data set was originally written at a density 
of 800 bits per inch. 

• SYSIN DD defines a dummy control data set. Because the input is sequential 
and no user exits are provided, no utility control statements are required. 



In this example, a partitioned data set is to be copied and compared in two job 
steps. 

The example follows: 

//DISKDISK JOB 09#660, SMITH 

//STEPA EXEC PGM=IEBCOPY 

//SYSPRINT DD SYSOUT-A 

//SYSUT1 DD DSNAME=OLDSET,UNIT=2314,DISP=SHR, 

// VOLUME=SER=1 1 1 1 1 2 ,DCB=( RECFM=FB, LRECL=80 , 

// BLKSIZE=640 ) 

//SYSUT2 DD DSNAME=NEWMEMS,UNIT=2314,DISP=( ,PASS ), 

// VOLUME=SER=1 1 1 1 1 3 , SPACE=( TRK, ( 5,5,5 ) ), 

// DCB=( RECFM=FB , LRECL=80 , BLKSIZE=640 ) 

//SYSUT3 DD UNIT=23 1 4 , SPACE=( TRK, ( 1 ) ) 

//SYSUT4 DD UNIT=2314,SPACE=(TRK,( 1 ) ) 

//SYSIN DD * 

COPY OUTDD=S YSUT2 , INDD=S YSUT 1 
SELECT MEMBER=(A,B,D,E,F) 

/* 

//STEPB EXEC PGM=IEBCOMPR 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=OLDSET,DISP=( OLD, KEEP) 

//SYSUT2 DD DSNAME=NEWMEMS,DISP=( OLD, KEEP) 

//SYSIN DD * 

COMPARE TYPORG=PO 

EXITS ERROR=SEEERROR 
/* 

The first job step copies the data set and passes the original and copied data sets 
to the second job step. The second job step compares the two data sets. 

The control statements for the IEBCOMPR job step are discussed below: 

• SYSUTl DD defines a blocked input data set that is passed from the preceding 
job step. The data set resides on a 2314 volume. 

• SYSUT2 DD defines a blocked input data set that is passed from the preceding 
job step. The data set resides on a 2314 volume. 

• SYSIN DD defines the control data set, which contains a COMPARE statement 
and an EXITS statement. 

• COMPARE specifies partitioned organization. 

• EXITS specifies that a user routine, SEEERROR, is to be used. 

Because the input data set names are not identical, the data sets can be retrieved 
by their data set names. 
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IEBCOPY Program 



IEBCOPY is a data set utility used to copy one or more partitioned data sets or to 
merge partitioned data sets. (See "Introduction" for general data set utility 
information.) One partitioned data set can be unloaded to a sequential data set. 
The sequential data set created by an unload operation can be loaded to any 
direct access device. Specified members of a partitioned or unloaded data set can 
be selected for, or excluded from, a copy, unload, or load process. 

IEBCOPY can be used to: 

Create a backup copy. 

Copy one or more data sets per copy operation. 

Copy one partitioned data set to a sequential data set (unload). 

Copy one or more data sets created by an unload operation to any direct 
access device (load). 

Select members from a data set to be copied, unloaded, or loaded. 

Replace identically named members on data sets (except when unloading). 

Replace selected data set members. 

Rename selected members. 

Exclude members from a data set to be copied, unloaded, or loaded. 

Compress partitioned data sets in place (except when the data set is an 
unloaded data set). 

Merge data sets (except when unloading). 

Re-create a data set that has exhausted its primary, secondary, or directory 
space allocation. 

In addition, IEBCOPY automatically lists the number of unused directory blocks 
and the number of unused tracks available for member records in the output 
partitioned data set. If LlST=NO is coded (see "COPY Statement"), the names of 
copied, unloaded, or loaded members listed by the input data set are suppressed. 

When copying members that have aliases, the following should be noted: 

• When the main member and its aliases are copied, they exist on the output 
partitioned data set in the same relationship they had on the input partitioned 
data set. 

• When one alias is copied without its main member, it becomes a main 
member. 

• When two or more aliases are copied, unloaded, or loaded without the main 
member, the lowest alias (in alphameric collating sequence) becomes the main 
member; any remaining aliases become aliases of the new main member. Note 
that if an old main member name is present in an alias entry, it remains there. 

The rules for replacing or renaming members apply to both aliases and members; 
no distinction is made between them. Note, however, that the replace option 
does not apply to an unload operation. 

At the completion or termination of the program, the highest return code 
encountered within the program is passed to the calling program. 
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Creating a Backup Copy 

IEBCOPY can be used to create a backup copy of a data set by 
unloading™ copying in sequential organization™ a data set. A partitioned data set 
can be unloaded, totally or in part, to any tape volume or direct access device 
supported by BSAM. A data set is unloaded when physical sequential organization 
space allocation is specified for the output data set on a direct access device or 
when the output data set is a tape volume. To unload more than one partitioned 
data set to the same volume in one execution of IEBCOPY, multiple copy 
operations must be used and multiple sequential data sets must be allocated on 
the same volume. 



A data set with a physical sequential organization resulting from an unload 
operation can be unloaded a second time. 



Copying Data Sets 



IEBCOPY can be used to copy a partitioned data set, totally or in part, from one 
direct access volume to another. In addition, a data set can be copied to its own 
volume, provided its data set name is changed. If the data set name is not 
changed, the data set is compressed in place. 

Note that copied members are not reordered. Members are copied in the order in 
which they exist on the original data set. If the members are to be reordered, 
IEHMOVE can be used for the copy operation (see "IEHMOVE Program"). 

Copying an Unloaded Data Set to Direct Access 

Data sets created by an unload operation can be loaded to any direct access 
device. The output partitioned data set will have the same characteristics as it 
had before the operation. A load operation is requested by specifying a 
sequential input data set unloaded by IEBCOPY. 

Copying or Loading Data Sets 

Data sets can be copied or loaded, totally or in part, from one or more direct 
access volumes or tape volumes to a single direct access volume. To copy or load 
more than one input partitioned data set, specify more than one input data set 
(see "COPY Statement" below). The input data sets are copied or loaded in the 
order in which they are specified. 

Selecting Members to be Copied, Unloaded, or Loaded 

Members can be selected from one or more input data sets. Selected members 
are copied, unloaded, or loaded from the input data sets specified on the INDD 
statement preceding a select statement. (See "copy Statement" and "select 
Statement" in this chapter.) 

Selected members are searched for in a low-to-high (a-to-z) collating sequence, 
regardless of the order in which they are specified; however, they are copied in 
the same physical sequence in which they appear on the input partitioned data 
set. 

When selecting members from an input data set, remember that once a member 
is found it is not searched for on any subsequent input data set. Similarly, when 
all of the selected members are found, the copy or load step is terminated 
although all of the input data sets may not have been searched. For example, if 
members A and B are specified and A is found on the first of three input data 
sets, it is not searched for again; if B is found on the second input data set, the 
copy or load operation is successfully terminated after the second input data set 
has been processed, although both A and B may also exist on the third input data 
set. 
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However, if the first member name is not found on the first input data set, the 
second selected member is searched for; if it is not found, the third is searched 
for, and so on. This process continues until there are no more members to be 
searched for in this input data set. All the members that were found on the input 
data set are then processed for copying, unloading, or loading to the output data 
set. This process is repeated for the second input data set (except that the 
members that were found on the first input data set are not searched for again). 

Note: Only one data set can be processed if an unload operation is to be 
performed. 

Replacing Identically Named Members 

In many copy and load operations, the output partitioned data set may contain 
members that have names identical to the names of the input partitioned data set 
members to be copied or loaded. When this occurs, the user may specify that the 
identically named members are to be copied from the input partitioned data set 
to replace existing members. 

The replace option allows an input member to override an existing member on 
the output partitioned data set with the same name. The pointer in the output 
partitioned data set directory is changed to point to the copied or loaded 
member. 

If the replace option is not specified, input members are not copied when they 
have the same name as a member on the output partitioned data set. 

The replace option can be specified on the data set or member level. The level is 
specified on a utility control statement. 

When replace is specified on the data set level (specified on a COPY or INDD 
statement), the input data is processed as follows: 

• In a full copy or load process, all members on an input partitioned data set are 
copied to an output partitioned data set; members whose names already exist 
on the output partitioned data set are replaced by the members copied or 
loaded from the input partitioned data set. 

• In a selective copy or load process, all selected members on an input 
partitioned data set are copied or loaded to an output partitioned data set; all 
selected members found are copied or loaded and members whose names 
already exist on the output partitioned data set are replaced by the found 
members copied or loaded from the input partitioned data set. 

• In an exclusive copy process, all nonexcluded members on input partitioned 
data sets are copied or loaded to an output partitioned data set; nonexcluded 
input members whose names already exist on the output partitioned data set 
replace those duplicate named members on the output partitioned data set. 

When replace is specified on the member level (specified on a SELECT 
statement), only selected members for which replace is specified are copied or 
loaded, and identically named members on the output partitioned data set are 
replaced. 

There are differences between full, selective, and exclusive copy or load 
processing. These differences should be remembered when specifying the replace 
option and all of the output data sets contain member names common to some or 
all of the input partitioned data sets being copied or loaded. These differences 
are: 

• When a full copy or load is performed, the output partitioned data set contains 
the replacing members that were on the last input partitioned data set copied. 



I BRCOPY Program 6-3 



• When a selective copy or load is performed, the output partitioned data set 
contains the selected replacing members which were found on the earliest input 
partitioned data set searched. Once a selected member is found, it is not 
searched for again; therefore, once found, a selected member is copied or 
loaded. If the same member exists on another input partitioned data set it is 
not searched for, and hence, not copied or loaded. 

• When an exclusive copy or load is performed, the output partitioned data set 
contains the nonexcluded replacing members that were on the last input 
partitioned data set copied or loaded. 

Replacing Selected Members 

The user may specify the replace option on either the data set or the member 
level when members are being selected for copying or loading. 

If the replace option is specified on the data set level, all selected members found 
on the designated input data sets replace identically named members on the 
output partitioned data set. This is limited by the fact that once a selected 
member is found it is not searched for again. 

If the replace option is specified on the member level, the specified members on 
the input data set replace identically named members on the output partitioned 
data set. Once a member is found it is not searched for again. (See "Replacing 
Identically Named Members" earlier in this chapter.) 

Renaming Selected Members 

Selected members on input data sets can be copied and renamed on the output 
data set. However, in the case of a copy or load operation, if the new name is 
identical to a member name on the output data set, the input member is not 
copied or loaded unless the replace option is also specified. See "SELECT 
Statement" below for information on renaming selected members. 

Note: Renaming is not physically done to the input data set directory entry. The 
output data set directory, however, will contain the new name. 

Excluding Members from a Copy Operation 

Members from one or more input data sets can be excluded from a copy, unload, 
or load operation. The excluded member is searched for on every input data set 
in the copy, unload, or load operation and is always omitted. Members are 
excluded from the input data sets named on an INDD statement that precedes the 
EXCLUDE statement. (See "COPY Statement" and "EXCLUDE Statement" in this 
chapter.) 

The replace option can be specified on the data set level in an exclusive copy or 
load, in which case, nonexcluded members on the input data set replace 
identically named members on the output data set. See "Replacing Identically 
Named Members" earlier in this chapter for more information on the replace 
option. 

Compressing a Data Set 

A compressed data set is one that does not contain embedded, unused space. 
After copying or loading one or more input partitioned data sets to a new output 
partitioned data set (by means of a selective, exclusive, or full copy or load that 
does not involve replacing members), the output partitioned data set contains no 
embedded, unused space. 

To make unused space available, either the entire data set must be scratched or it 
must be compressed in place. A compressed version can be created by specifying 
the same data set for both the input and the output parameters in a full copy 
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Merging Data Sets 



Re-creating a Data Set 



Input and Output 



step. A backup copy of the partitioned data set to be compressed in place should 
be kept until successful completion of an in-place compression is indicated (by an 
end-of-job message and a return code of 00). 

An in-place compression does not release extents assigned to the data set. 

Note: When the same ddname is specified for the INDD and OUTDD keywords 
(see "COPY Statement" below) and the DD statement specifies a block size 
different from the block size specified in the DSCB, the DSCB block size is 
overridden; however, no physical reblocking or deblocking is performed by 
IEBCQPY. 



A merged data set is one to which an additional member is copied or loaded, it is 
created by copying or loading the additional members to an existing output 
partitioned data set; the merge operation — the ordering of the output partitioned 
data set's directory — is automatically performed by IEBCOPY. 

Note: If there is a question about whether or not enough directory blocks are 
allocated to the output partitioned data set to which an input data set is being 
merged, the output partitioned data set should be re-created prior to the merge 
operation. 



A data set can be re-created by copying or loading it and allocating a larger 
amount of space than was allocated for the original data set. This application of 
IEBCOPY is especially useful if insufficient directory space was allocated to a data 
set. Space cannot be allocated in this manner for an existing partitioned data set 
into which members are being merged. 



IEBCOPY uses the following input: 

• An input data set, which contains the members to be copied, loaded, or 
merged into a partitioned data set or unloaded to a sequential data set. 

• A control data set, which contains utility control statements. The control data 
set is required if members are to be selected for or excluded from a copy, 
unload, load, or merge operation. 

If the control data set is null, a full copy is attempted from the input partitioned 
data set to the output partitioned data set. In this case, SYSUT1 and SYSUT2 are 
required ddnames for the input partitioned data set and output partitioned data 
set, described under "Job Control Statements" below. 

Note: When merging into or compressing system libraries, do not specify 
DISP=SHR. The results of a merge into or compress of the current SYS1.LINKLIB 
or SYSl.SVCLIB would be unpredictable. 

IEBCOPY produces the following output: 

• An output data set, which contains the copied, merged, unloaded, or loaded 
data. The output data set is either a new data set (from a copy, load, or 
unload) or an old data set (from a merge, compress-in-place, copy, or load). 

• A message data set, which contains informational messages (for example, the 
names of copied, unloaded, or loaded members) and error messages, if 
applicable. 
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Control 



• Spill data sets, which are temporary data sets used to provide space when not 
enough main storage is available for the input and/ or output partitioned data 
set directories. These data sets are opened only when needed. 

Note: Refer to 0S/VS1 Storage Estimates, GC24-5094, or 0S/VS2 Storage 
Estimates, GC28-0604, to determine when spill data sets are required; see "Space 
Allocation" below for a description of how to determine the amount of space to 
allocate. 

The following direct access devices may be used for input, output, and utility 
data sets: 

• 2314 Direct Access Storage Facility 

• 2319 Direct Access Storage Facility 

• 3330 Disk Storage 

• 2305 Fixed Head Storage 

• 3330-1 Disk Storage 

• 3340 Disk Storage 

Any combination of these devices is acceptable to IEBCOPY. 

The following magnetic tape devices may be used for unloaded data sets: 

• 2400 series 

• 3410 series 

• 3420 series 

Note: The sequentially organized output from an unload operation or the 
sequentially organized input for a load operation may also reside on a direct 
access device. 

IEBCOPY produces a return code to indicate the results of program execution. 
The return codes and their meanings are: 

• 00, which indicates successful completion. 

• 04, which indicates a condition from which recovery may be possible. 

• 08, which indicates an unrecoverable error. The job step is terminated. 



IEBCOPY is controlled by job control statements and utility control statements. 



Job Control Statements 

Table 6-1 shows the job control statements necessary for using IEBCOPY. 



6-6 OS/VS Utilities 



Table 6-1. IEBCOPY Job Control Statements 

Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (PGM=IEBCOPY) or, if the job control 

statements reside in the procedure library, the procedure name. This 
statement can include optional PARM information to define the size of the 
buffer to be used; see "parm Information on the EXEC Statement" below. 

SYSPRINT DD Defines the sequential message data set used for listing statements and 

messages. This data set can be written to a system output device, a tape 
volume, or a direct access volume. 

anynamel DD Defines an input partitioned data set. anynamel DD statements can 

describe partitioned data sets on direct access devices or sequential data 
sets, created as a result of unload operations, on tape or direct access 
devices. The data set can be defined by a data set name, as a cataloged 
data set, or as a data set passed from a previous job step. 

anyname2 DD Defines an output partitioned data set. anyname2 DD statements can 

describe partitioned data sets on direct access devices or sequential data 
sets, created as a result of unload operations, on tape or direct access 
devices. 

SYSUT3 DD Defines a spill data set on a direct access device. SYSUT3 is used when 

there is no space in main storage for some or all of the current input 
partitioned data set's directory entries. SYSUT3 may also be used when not 
enough space is available in main storage for retaining information during 
table sorting. 

SYSUT4 DD Defines a spill data set on a direct access device. SYSUT4 is used when 

there is no space in main storage for the current output partitioned data 
set's merged directory and the output partitioned data set is not new. 

SYSIN DD Defines the control data set. The control data set normally resides in the 

input stream; however, it can reside on a system input device, a tape 
volume, or a direct access volume. 

Fixed or variable records can be reblocked. Reblocking or deblocking is done if 
the block size of the input partitioned data set is not equal to the block size of 
the output partitioned data set. Reblocking or deblocking cannot be done if 
either the input or the output data set has undefined format records, keyed 
records, track overflow records, note lists, or user TTRN's, or if compress-in-place 
is specified. 

An unloaded partitioned data set will have a variable spanned record format. 
When an unloaded data set is subsequently loaded, the output data set will have 
the same characteristics it had before the unload operation, unless specified 
differently by the user. 

For unload and load operations, requests are handled in the same way as for a 
copy operation. 

Table 6-2 shows how input record formats can be changed. In addition, any 
record format can be changed to the undefined format (in terms of its 
description in the DSCB). 

Table 6-2. Changing Input Record Format Using IEBCOPY 

Input Output 

Fixed Fixed Blocked 

Fixed Blocked Fixed 

Variable Variable Blocked 

Variable Blocked Variable 



System data sets should not be compressed in place unless the subject partitioned 
data set is made non-sharable. The libraries in which IEBCOPY resides 
(SYS1.LINKLIB and SYS1.SVCLIB) must not be compressed by IEBCOPY unless 
IEBCOPY is first transferred to a JOBLIB. 
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Refer to OS/VS Data Management Services Guide, GC26-3783, for information on 
estimating space allocations. 

Refer to 0S/VS1 Storage Estimates, GC24-5094, or 0S/VS2 Storage Estimates, 
GC28-0604, to determine when spill data sets are required; see "Space 
Allocation" below for a description of how to determine the amount of space to 
allocate. 



Restrictions 



• SYSPRINT and SYSIN are mandatory DD statements. The block size for the 
SYSPRINT data set must be a multiple of 121. The block size for the SYSIN 
data set must be a multiple of 80. Any blocking factor may be specified for 
these data sets, with a maximum allowable block size of 32,767 bytes. 

• The SYSPRINT DD statement must define a data set with fixed blocked or 
fixed records. 

• INPUT DD and OUTPUT DD statements are required. There must be one INPUT 
DD statement for each unique data set used for input and one OUTPUT DD 
statement for each unique data set used for output in the job step. 

• Input data sets cannot be concatenated. 

• The SYSIN DD statement must define a data set with fixed block or fixed 
records. 

PARM Information on the EXEC Statement 

The EXEC statement for IEBCOPY can contain PARM information that is used to 
define the number of bytes used as a buffer. The PARM parameter can be coded: 

PARM= ' SIZE=nnnnnnnn[K] ' 

The nnnnnnnn can be replaced by one to eight digits. The K causes the 
nnnnnnnn to be multiplied by 1024. 

If PARM is not specified, is invalidly specified, or a value below the minimum 
buffer size is specified, IEBCOPY defaults to the minimum buffer size, which is 
twice the maximum of the input or output block sizes or the input or output 
track capacities. 

The maximum buffer size that can be specified is equal to the remaining storage 
available in the partition when the buffer is allocated. If the value specified in 
PARM exceeds this maximum, IEBCOPY defaults to the maximum. 



Space Allocation 



Sometimes it is necessary to allocate space on spill data sets (SYSUT3 and 
SYSUT4). The space to be allocated for SYSUT3 depends on the number of 
members to be copied or loaded. The space to be allocated for SYSUT4 depends 
on the number of directory blocks to be written to the output data set. 

To conserve space on the direct access volume, an initial quantity and a 
secondary quantity for space allocation may be used, as shown in the following 
SPACE parameter: 

SPACE=(c,(x,y)) 

The c value should be a block length of 80 for SYSUT3 and of 256 for SYSUT4. 
The x value is the number of blocks in the primary allocation, and the y value is 
the number of blocks in a secondary allocation. 

For SYSUT3, x + 15y must be equal to or greater than the number of entries in 
the largest input partitioned data set in the copy operation, multiplied by 1.05. 
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For SYSUT4, x + 15y must be equal to or greater than the number of blocks 
allocated to the largest output partitioned data set directory in the mBCOPY job 
step. 

For example, if there are 700 members on the largest input partitioned data set, 
space could be allocated for SYSUT3 as follows: 

SPACE=(80,(25,45)) 

However, the total amount of space required for SYSUT3 in the worst case is 
used only if needed. If space is allocated in this manner for SYSUT4, the user 
must specify in his SYSUT4 DD statement: 

DCB = (KEYLEN = 8) 

Note that IEBCOPY ignores all other DCB information specified for SYSUT3 
and/or SYSUT4. Multivolume SYSU 13 and SYSUT4 data sets are not supported. 

Utility Control Statements 

IEBCOPY is controlled by the following utility control statements: 

• COPY statement, which indicates the beginning of a COPY operation. 

• SELECT statement, which specifies which members in the input data set are to 
be copied. 

• EXCLUDE statement, which specifies members in the input data set to be 
excluded from the copy step. 

In addition, when INDD, a COPY statement parameter, appears on a card other 
than the COPY statement, it is referred to as an INDD statement; it can function 
as a control statement in this context. 

Utility control statements may be continued on subsequent cards provided that 
all the data is contained in columns 2 through 71. Control statement operation 
and keyword parameters can be abbreviated to their initial letters; COPY, INDD, 
OUTDD, and LIST can be abbreviated to C, I, O, and L. 



COPY Statement 



The COPY Statement is required to initiate one or more IEBCOPY copy, unload, 
or load operations. Any number of operations can follow a single copy 
statement; any number of COPY statements can appear within a single job step. 

Note: IEBCOPY copy, unload, and load operations are specified by a combination 
of job control language and utility control statements. For a full discussion of 
how these operations are specified, see "IEBCOPY Examples" later in this 
chapter. 

A COPY statement must precede a SELECT or EXCLUDE statement when 
members are selected for or excluded from a copy, unload, or load step. In 
addition, if an input ddname is specified on a separate INDD statement, it must 
follow the COPY statement and precede the SELECT or EXCLUDE statement to 
which it applies. If one or more INDD statements are immediately followed by 
the /* card or another COPY statement, a full copy, unload, or load is invoked 
onto the most recent output partitioned data set previously specified. 
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IEBCOPY uses a copy operation/copy step concept. 1 A copy operation starts with 
a COPY statement and continues until either another COPY statement or the end 
of the control data set is found. Within each copy operation, one or more copy 
steps are present. Any INDD statement directly following a SELECT or EXCLUDE 
statement marks the beginning of the next copy step and the end of the 
preceding copy step within the copy operation. If such an INDD statement cannot 
be found in the copy operation, then the copy operation consists of only one 
copy step. 

Figure 6-1 shows the copy operation/copy step concept. Two copy operations 
are shown in the figure: the first begins with the statement containing the name 
COPOPERl, and the second begins with the statement containing the name 
COPOPER2. 

There are two copy steps within the first copy operation shown in Figure 6-1: 
the first begins with the COPY statement and continues through the two SELECT 
statements; the second begins with the first INDD statement following the two 
select statements and continues through the EXCLUDE statement preceding the 
second COPY statement. There are two copy steps within the second copy 
operation: the first begins with the COPY statement and continues through the 
select statement; the second begins with the INDD statement immediately 
following the SELECT statement and ends with the same /* (delimiter) statement 
that ended the copy operation. 



Job control statements 



1st 
Copy 
Operat ion 

hti:i' 1 


COPOPER1 


CDPY 

SELECT 
SELECT 


(IUTDD=AA,INDD=ZZ 

INDD=BB',CC 

INDD^DD 

INDD=EE 

MEMBER=MEMA,MEMB 

MEMBER=MEMC 




S-W 2 




EXCLUDE 


INDD=GG 
INDD=HH 
MEMBER=MEMD,MEMH 




2nd 

Copy 

Operation 

STEP 1 


COPOPER2 


COPY 
SELECT 


OUTDD=YY,I=(MM,PP) 
MEMBER=MEMB 


LIST=NO 


STEP 7 






INDD=KK 
INDD=LL,NN 





Figure 6-1. Multiple Copy Operations Within a Job Step 

The format of the COPY statement is: 

[label] COPY OUTDD =ddname 

[,INDD = {ddname 1 [,ddname2] ...} 

{ddnamel[,ddname2][,(ddname2,R)]...} 
{((ddnamel,R)[,ddname2]...)}] 

[,LIST=NO] 

where: 

OUTDD=c/dname 

specifies the name of the output partitioned data set. One ddname is required 
for each copy, unload, or load operation; the ddname used must be specified 
on a DD statement. 



1 The same applies to an unload or load operation or step. 
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INDD= 

specifies the names of the input partitioned data sets. INDD may, optionally, be 
placed on a separate card following a COPY statement containing the OUTDD 
parameter, another INDD statement, a SELECT statement, or an exclude 
statement. These values can be coded: 

ddname 

specifies the ddname, which is specified on a DD statement, of an input 
data set. For an unload operation, only one ddname may be specified per 
COPY statement. If more than one ddname is specified in the case of a copy 
or load operation, the input data sets are processed in the same sequence as 
the ddnames are specified. 

R 

specifies that all members to be copied or loaded from this input data set 
are to replace any identically named members on the output partitioned 
data set. (In addition, members whose names are not on the output 
partitioned data set are copied or loaded as usual.) When this option is; 
specified with the INDD parameter, it does not have to appear with the 
MEMBER parameter (discussed in "SELECT Statement" in this chapter) in a 
selective copy operation. When this option is specified, the ddname and the 
R parameter must be enclosed in a set of parentheses; if it is specified with 
the first ddname in INDD, the entire field, exclusive of the INDD parameter, 
must be enclosed in a second set of parentheses. 

LIST=NO 

specifies that the names of copied members are not to be listed on SYSPR1NT 
at the end of each input data set. If LIST is not coded, the names of copied 
members are listed. 

Note: The control statement operation and keyword parameters can be 
abbreviated to their initial letters; for example, COPY can be abbreviated to c and 
OUTDD can be abbreviated to O. 

Only one INDD and one OUTDD keyword may be placed on a single card. OUTDD 
must appear on the COPY statement. When INDD appears on a separate card, no 
other operands may be specified on that card. 

INDD may appear on a separate card; if this option is selected, INDD is not 
preceded by a comma. 

If there are no keywords on the COPY card, compatibility with the previous 
version is implied. In this case, comments may not be placed on this card. 

If more than one ddname is specified, the input partitioned data sets are 
processed in the same sequence as that in which the ddnames are specified. 

A full copy, unload, or load is invoked only by specifying different input and 
output ddnames; that is, by omitting the SELECT or exclude statement from 
the copy step. 

The compress-in-place function is valid for partitioned data sets. 
Compress-in-place is normally invoked by specifying the same ddname for both 
the OUTDD and INDD parameters of a COPY statement. If multiple entries are 
made on the INDD statement, a compress-in-place will occur if one of the input 
ddnames is the same as the ddname specified by the OUTDD parameter of the 
COPY statement, provided that SELECT or EXCLUDE is not specified. 

The compress-in-place function cannot be performed for the following: 

• An unloaded data set. 

• A data set with track overflow records. 
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SELECT Statement 



• A data set with keyed records. 

• A data set for which reblocking is specified in the DCB parameter. 

• An unmovable data set. 

When a compression is invoked by specifying the same ddname for the INDD and 
OUTDD parameters, and the DD statement specifies a block size that differs from 
the block size specified in the DSCB, the DSCB block size is overridden; however, 
no physical reblocking or deblocking is done by IEBCOPY. 



The SELECT statement specifies members to be selected from input data sets to 
be copied, loaded, or unloaded to an output data set. This statement is also used 
to rename and/or replace selected members on the output data set. More than 
one SELECT statement may be used in succession, in which case the second and 
subsequent statements are treated as a continuation of the first. 

The SELECT statement must follow either a COPY statement that includes an 
INDD parameter or one or more INDD statements. A SELECT statement cannot 
appear with an EXCLUDE statement in the same copy, unload, or load step. 

When a selected member is found on an input data set, it is not searched for 
again, regardless of whether it the member is copied, unloaded, or loaded. A 
selected member will not replace an identically named member on the output 
partitioned data set unless the replace option is specified on either the data set or 
member level. (For a description of replacing identically named members see 
"Replacing Identically Named Data Set Members," and "Replacing Selected 
Members" in this chapter.) In addition, a renamed member will not replace a 
member on the output partitioned data set that has the same new name as the 
renamed member, unless the replace option is specified. 

The format of the SELECT statement is: 



[label] SELECT MEMBER = 



{name...} 

l[(](name.,R)...[)J}[,...] 

{[(Jname,newname[,RJ...[)]} 



where: 



MEMBER = 

specifies the members to be selected from the input data set. The values that 
can be coded are: 



R 



name 

specifies the name of a member that is to be selected in a copy step. Each 
member name specified within one copy step must be unique; that is, 
duplicate names cannot be specified as either old names, or new names, or 
both, under any circumstances. 

newname 

specifies a new name for a selected member. The member is copied, 
unloaded, or loaded to the output partitioned data set using its new name. 
If the name already appears on the output partitioned data set, the member 
is not copied unless replacement (R) is also specified. 

specifies that the input member is to replace any identically named member 
that exists on the output partitioned data set. The replace option is not valid 
for an unload operation. 
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EXCLUDE Statement 



IEBCOPY Examples 



Note: The control statement operation and keyword parameter can be 
abbreviated to their initial letters; select can be abbreviated to s and MEMBiER 
can be abbreviated to M. 

To rename a member, the old member name is specified in the select 
statement, followed by the new name and, optionally, the R parameter. When this 
option is specified, the old member name and new member name must be 
enclosed in a set of parentheses. When any option within parentheses is specified 
anywhere in the MEMBER field, the entire field, exclusive of the MEMBER 
keyword, must be enclosed in a second set of parentheses. 



The EXCLUDE statement specifies members to be excluded from the copy, 
unload, or load step. Unlike the selective copy, unload, or load, an exclusive 
copy, unload, or load causes all members specified on each EXCLUDE statement 
to be omitted from the operation. 

More than one EXCLUDE statement may be used in succession, in which case the 
second and subsequent statements are treated as a continuation of the first. The 
EXCLUDE statement must follow either a COPY statement that includes an INDD 
parameter or one or more INDD statements. An exclude statement cannot 
appear with a SELECT statement in the same copy, unload, or load step; 
however, both may be used following a COPY statement for a copy or load 
operation. 

The format of the EXCLUDE statement is: 

[label] EXCLUDE MEMBER=[(]membernamel[,membername2]...[)J 

where: 

MEMBER = [Qmembername 1 [>membername2] ...[)] 

specifies members on the input data set that are not to be copied, unloaded, or 
loaded to the output data set. The members are not deleted from the input 
data set unless the entire data set is deleted. (This can be done by specifying 
DISP=DELETE in the operand field of the input DD job control statement ) 
Each member name specified within one copy step must be unique. 

Note: The control statement operation and keyword parameter can be 
abbreviated to their initial letters; EXCLUDE can be abbreviated to E and MEMBER 
can be abbreviated to M. 



The following examples illustrate some of the uses of IEBCOPY. Table 6-3 can be 
used as a quick reference guide to IEBCOPY examples. The numbers in the 
"Example" column point to examples that follow. 
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Table 6-3. iebcopy Example Directory 



Operation Device 
COPY 2314 Disk 



COPY 


2314 Disk, 




3330 Disk 


COPY 


3330 Disk, 




2314 or 




2319 Disk 1 


COPY 


3330 Disk, 




2314 Disk 



COPY 



COPY 



COPY 



3330 Disk, 
2314 Disk 



2314 Disk, 
3330 Disk, 
and 2305 Fixed 
Head Storage 

2314 Disk 



COPY 



COPY and 2314 Disk 
Compress- 2400 Tape 
in-place 



COPY and 
Compress- 
in-place 


3330 Disk, 
2314 Disk 


COPY 


2314 Disks 


COPY 


2314 Disks 


Unload 


2314 Disk, 
2400 Tape 


Load 


2400 Tape, 
2314 Disk 



Unload and 2314 Disks, 
COPY 2400 Tape 



Unload, 3330 Disk, 

Load, and 2400 Tape, 
COPY 2314 Disk 



Comments Example 

Full Copy. The input and output 

data sets are partitioned. 1 

Multiple input partitioned data sets. 

Fixed blocked and fixed record formats. 2 

All members are to be copied. 

Identically named members on the 

output data set are to be replaced. 

The input and output data sets are 

partitioned. 3 

Selected members are to be copied. 

Variable blocked data set is to be 

created. Record formats are variable 

blocked and variable. The input and 

output data sets are partitioned. 4 

Selected members are to be copied. 

One member is to replace an 

identically named member on the 

output data set. The input and 

output data sets are partitioned. 5 

Selected members are to be copied. 

Members found on the first input data set 

replace identically named members on 

the output data set. The input and 

output data sets are partitioned. 6 

Selected members are to be copied. 

Two members are to be renamed. One 

renamed member is to replace an 

identically named member on the 

output data set. The input and 

output data sets are partitioned. 7 

Exclusive Copy. Fixed blocked and 

fixed record formats. The input and 

output data sets are partitioned. 8 

Copy a partitioned data set to 

tape (unload) and compress-in- 

place if the first step is successful. 9 

Full copy to be followed by a compress- 

in-place of the output data set. Replace 

specified for one input data set. The 

input and output data sets are 

partitioned. 10 

Multiple copy operations. The input and 

output data sets are partitioned. 1 1 

Multiple copy operations. 12 

A partitioned data set is to be 

unloaded to tape. 13 

An unloaded data set is to be loaded 

to disk. 14 

A partitioned data set is to be loaded 

to tape to create a backup copy. If 

the unload is successful, the partitioned 

data set is compressed in place. 15 

Selected members are to be unloaded, 

loaded, and copied. The input data set 

is partitioned; the output data set is 

sequential. 16 



2314 Disk 



The 2319 disk is functionally equivalent to the 2314 disk; 
to use the 2319, specify 2314 in the control statement. 
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IEBCOPY Example 1 



IEBCOPY copy, unload, and load operations are specified by a combination of job 
control language and utility control statements. The OUTDD and INDD keyword 
parameters on COPY statements* name DD statements that define the input and 
output data sets to be copied, unloaded, or loaded. For example: 

//COPY JOB accountnb, "name' ,MSGLEVEL=( 1,1) 

//JOBSTEP EXEC PGM=IEBCOPY 

//SYSPRINTDD SYSOUT=A 

//IN DD DSN=xxxxx , UNIT=yyyy , VOL=SER=yyyyyy , DISP=OLD 

//OUT DD DSN=xxxxx,UNIT=yyyy,VOL=SER=yyyyyy, 

//DISP=NEW,SPACE=xxxx 

//SYSUT3 DD DSN=TEMP1 ,UNIT=SYSDA,DISP=( NEW, DELETE), 

//SPACE=( CYL, (2,2)) 

//SYSUT4 DD DSNAME=TEMP2,UNIT=DA,DISP=( NEW, DELETE ), 

//SPACE=(CYL,( 2,2 ) ) 

//SYSIN DD * 

COPY OUTDD=OUT,INDD=IN 
/* 

The INDD parameter names the IN DD statement as the statement that contains 
the identification of the input data set. 

The OUTDD parameter names the OUT DD statement as the statement that 
contains the indentification of the output data set. 

The characteristics of the input and output data sets depend on the operation to 
be performed, as follows: 

• If a data set is to be copied, the input and output data sets must both be 
partitioned data sets. 

• If a data set is to be loaded, the input data set may be either partitioned or 
sequential; the output data set must be partitioned. 

• If a data set is to be unloaded, the input data sei must be either a partitioned 
data set or a sequential data set that was created as a result of a previous 
unload operation. The output data set may reside on either a direct access or 
tape volume. If the output data set is to reside on a direct access volume, the 
organization of the data set must be specified as sequential. To specify 
sequential organization for a direct access data set, specify the SPACE 
parameter, omitting the directory or index value. 



In this example, a partitioned data set (DATASET5) is to be copied from one disk 
volume to another. Figure 6-2 shows the input and output data sets before and 
after processing. 

The example follows: 

//COPY JOB 06#990,MCEWAN 

//JOBSTEP EXEC PGM-IEBCOPY 

//SYSPRINT DD SYSOUT=A 

//IN0UT4 DD DSNAME=DATASET4,UNIT=2314,VOL=SER=1 1 1 1 12, 

// DISP=(NEW,KEEP),SPACE=(TRK,( 5,1,2)) 

DSNAME=DATASET5,UN1T=2314,V0L=SER=1 11113, 

UNIT=23 1 4 , SPACE=( TRK, ( 1 ) ) 
UNIT=2314,SPACE=( TRK, ( 1 ) ) 
* 

OUTDD=INOUT4 , INDD-IN0UT5 



//INOUT5 


DD 


// DISP=SHR 


//SYSUT3 


DD 


//SYSUT4 


DD 


//SYSIN 


DD 


COPYOPER 


COPY 


/* 
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Figure 6-2. Copying a Partitioned Data Set — Full Copy 

The control statements are discussed below: 

• INOUT4 DD defines a partitioned data set (DATASE:I4). This data set is new 
and is to be kept after the copy operation. Five tracks are allocated for the 
data set on a 2314 volume. Two blocks are allocated for directory entries. 

• INOUT5 DD defines a partitioned data set (DATASET5), which resides on a 
2314 volume and contains two members (A and C). 

• SYSUT3 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 

• SYSUT4 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 

• SYSIN DD defines the control data set, which follows in the input stream. The 
data set contains a COPY statement. 

• COPY indicates the start of the copy operation. The absence of a SELECT or 
EXCLUDE statement causes a default to a full copy. The OUTDD parameter 
specifies INOUT4 as the DD statement for the output data set (DATASET4); the 
INDD parameter specifies INOUT5 as the DD statement for the input data set. 
After the copy operation is finished, the output data set (DATASET4) will 
contain the same members that are on the input data set (DATASET5); 
however, there will be no embedded, unused space on DATASET4. 

The temporary spill data sets may or may not be opened, depending on the 
amount of main storage available; therefore, it is suggested that the SYSUT3 and 
SYSUT4 DD statements always appear in the job stream. 
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IEBCOPY Example 2 



In this example, members are to be copied from three input partitioned data sets 
(DATASETl, DATASET5, and DATASET6) to an existing output partitioned data set 
(DATASET2). The sequence in which the control statements occur controls the 
manner and sequence in which partitioned data sets are processed. Figure 6-3 
shows the input and output data sets before and after processing. 
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Figure 6-3. Copying from Three Input Partitioned Data Sets 

The example follows: 

//COPY JOB 06#990,MCEWAN 

//JOBSTEP EXEC PGM=IEBCOPY 

//SYSPRINT DD SYSOUT=A 

//INOUT 1 DD DSNAME-DATASET 1 , UNIT=2 3 1 4 , VOL=SER= 111112, 

// DISP=SHR 

//INOUT5 DD DSNAME=DATASET5,UNIT=3330,VOL=SER=1 1 1 1 14, 

// DISP=OLD 

// INOUT2 DD DSNAME=DATASET2 , UNIT= 33 30 , VOL=SER= 111115, 

// DISP=( OLD, KEEP) 

//INOUT6 DD DSNAME=DATASET6 , UNIT=3 330 , VOL=SER=1 11117, 

// DISP-( OLD, DELETE) 

//SYSUT3 DD UNIT=2314,SPACE=(TRK,( 1 ) ) 

//SYSUT4 DD UNIT=2314,SPACE=(TRK,( 1 ) ) 

//SYS IN DD * 

COPYOPER COPY OUTDD=INOUT2 

INDD- INOUT 1 

INDD=INOUT6 

INDD=INOUT5 
/* 
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IEBCOPY Example 3 



The control statements are discussed below: 

• inouti Dl) defines a partitioned data set (DATASF.T1). This data set, which 
resides on a 2314 volume, contains three members (A, B, and F) in fixed 
format with a logical record length of 80 bytes and a block size of 80 bytes. 

• INOUT5 DD defines a partitioned data set (DATASLT5), which resides on a 
3330 volume. This data set contains two members (A and C) in fixed blocked 
formal with a logical record length of 80 bytes and a block size of 160 bytes. 

• INOUT2 Dl) defines a partitioned data set (DATASET2), which resides on a 
3330 volume. This data set contains two members (C and E) in fixed blocked 
format. The members have a logical record length of 80 bytes and a block size 
of 240 bytes. 

• iNOUTfc DD defines a partitioned data set (DATASET6), which resides on a 
3330 volume. This data set contains three members (B, C, and D) in fixed 
blocked format with a logical record length of 80 bytes and a block size of 
400 bytes. This data set is to be deleted when processing is completed. 

• SYSi rn DD defines a temporary spill data set. One track is allocated on a 
23 14 volume. 

• SYSUT4 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 

• sysin DD defines the control data set, which follows in the input stream. The 
data set contains a COPY statement and three INDD statements. 

• COPY indicates the start of the copy operation. The absence of a SELECT or 
exclude statement causes a default to a full copy. The OUTDD parameter 
specifies 1NOUT2 as the DD statement for the output data set (DATASET2). 

« The first INDD statement specifies INOUTI as the DD statement for the first 
input data set (DATASETl) to be processed. All members (A, B, and F) are 
copied to the output data set (DATASET2). 

« The second indd statement specifies INOUT6 as the DD statement for the 
second input data set (DATASET6) to be processed. Processing occurs, as 
follows: (1) members B and c, which already exist on DATASET2, are not 
copied to the output data set (DATASET2), (2) member D is copied to the 
output data set <datasf.T2), and (3) all members on DATASET6 are lost when 
the data set is deleted. 

• The third INDD statement specifies INOUT5 as the DD statement for the third 
input data set (DATASET5) to be processed. No members are copied to the 
output data set (DATASEE2) because all of them exist on DATASET2. 

The temporary spill data sets may or may not be opened, depending on the 
amount of main storage available; therefore, it is suggested that the SYSUT3 and 
SYSUT4 DD statements always appear in the job stream. 



In this example, members are to be copied from an input partitioned data set 
(DATASET6) to an existing output partitioned data set (DATASET2). In addition, 
all copied members are to replace identically named members on the output 
partitioned data set. 

Figure 6-4 shows the input and output data sets before and after processing. 
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The example follows: 

//COPY JOB 06#990,MCEWAN 

//JOBSTEP EXEC PGM=IEBCOPY 

//SYSPRINT DD SYSOUT=A 

//INOUT2 DD DSNAME=DATASET2,UNIT==2314,VOL=SER=11 1 113, 

// DISP=OLD 

//INOUT6 DD DSNAME=DATASET6,UNIT=3330,VOL=SER=1 1 1 1 17, 

// DISP=( OLD, KEEP) 

//SYSUT3 DD UNIT=2314,SPACE=(TRK,( 1 ) ) 

//SYSUT4 DD UNIT=2314,SPACE=(TRK,( 1 ) ) 

//SYSIN DD * 

COPYOPER COPY OUTDD=INOUT2 

■ INDD=( ( INOUT6,R) ) 
/* 





Old memtiei 
C not pointed 
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Figure 6-4. Copy Operation with "Replace" Specified on the Data Set Level 
The control statements are discussed below: 

• INOUT2 DD defines a partitioned data set (DATASET2), which resides on a 
2314 volume. This data set contains two members (C and E). 

• INOUT6 DD defines a partitioned data set (DATASET6), which resides on a 
3330 volume. This data set contains three members (B. C, and D). 

• SYSUT3 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 

• SYSUT4 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 

• SYSIN DD defines the control data set, which follows in the input stream. The 
data set contains a COPY statement and an indd statement. 
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IEBCOPY Example 4 



• COPY indicates the start of the copy operation. The absence of a SELECT or 
EXCLUDE statement causes a default to a full copy. The OUTDD parameter 
specifies 1NOUT2 as the DD statement for the output data set (DATASET2). 

• 1NDD specifies INOUT6 as the DD statement for the input data set (DATASET6). 
Members B, C, and D are copied to the output data set (DATASET2). The 
pointer in the output data set directory is changed to point to the new 
(copied) member C; thus, the space occupied by the old member C is 
embedded unused space. Member C is copied even though the output data set 
already contains a member named "C" because the replace option is specified 
for all identically named members on the input data set; that is, the replace 
option is specified on the data set level. 

The temporary spill data sets may or may not be opened, depending on the 
amount of main storage available; therefore, it is suggested that the SYSUT3 and 
SYSUT4 DD statements always appear in the job stream. 



In this example, five members (A, C, D, E, and G) are to be selected from two 
input partitioned data sets (DATASET6 and DATASET3) to be copied to a new 
output partitioned data set (DATASET4). Figure 6-5 shows the input and output 
data sets before and after processing. 
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Figure 6-5. Copying Selected Members with Reblocking and Deblocking 
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//SYSUT3 


DD 


//SYSUT4 


DD 


//SYSIN 


DD 


COPYOPER 


COPY 



The example follows: 

//COPY JOB 06#990,MCEWAN 

//JOBSTEP EXEC PGM=IEBCOPY 

//SYSPRINT DD SYSOUT=A 

//INOUT2 DD DSNAME=DATASET2,UNIT=2314,VOL=SER=1 1 1 1 14, 

// DISP=( OLD, DELETE) 

//INOUT6 DD DSNAME=DATASET6,UNIT=3330,VOL=SER=1 1 1 1 17, 

// DISP=( OLD, KEEP) 

//INOUT4 DD DSNAME=DATASET4,UNIT=3330,VOL=SER=1 1 1 1 16, 

// DISP=(NEW,KEEP),SPACE=(TRK,( 5, ,2 ) ), 

// DCB=( RECFM=VB , LRECL=96 , BLKSIZE=300 )■ 

UNIT=2314,SPACE=(TRK, ( 1 ) ) 

UNIT=2314,SPACE=(TRK,( 1 ) ) 

* 

OUTDD=INOUT4 
INDD=INOUT6 
INDD=INOUT2 
SELECT MEMBER=C,D,E,A,G 
/* 

The control statements are discussed below: 

• INOUT2 DD defines a partitioned data set (DATASET2), which resides on a 
2314 volume. This data set contains two members (C and E) in variable , 
blocked format with a logical record length of 96 bytes and a block size of 
500 bytes. This data set is to be deleted when processing is completed. 

• INOUT6 DD defines a partitioned data set (DATASET6), which resides on a 
3330 volume. This data set contains three members (B, C, and D) in variable 
format with a logical record length of 96 bytes and a block size of 100 bytes. 

• INOUT4 DD defines a partitioned data set (DATASET4). This data set is new 
and is to be kept after the copy operation. Five tracks are allocated for the 
data set on a 3330 volume. Two blocks are allocated for directory entries. In 
addition, records are to be copied to this data set in variable blocked format 
with a logical record length of 96 bytes and a block size of 300 bytes. 

• SYSUT3 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 

• SYSUT4 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 

• SYSIN DD defines the control data set, which follows in the input stream. The 
data set contains a COPY statement, two indd statements, and a SELECT 
statement. 

• COPY indicates the start of the copy operation. The presence of a SELECT 
statement causes a selective copy. The OUTDD parameter specifies INOUT4 as 
the DD statement for the output data set (DATASET4). 

• The first indd statement specifies INOUT6 as the DD statement for the first 
input data set (DATASET6) to be processed. The members specified on the 
SELECT statement are searched for. The found members (C and D) are copied 
to the output data set (DATASET4) in the order in which they reside on the 
input data set, that is, in TTR order. In this case, member D is copied first, and 
then member C is copied. 

• The second INDD statement specifies INOUT2 as the DD statement for the 
second input data set (DATASET2) to be processed. The members specified on 
the SELECT statement and not found on the first input data set are searched 
for. The found member (E) is copied onto the output data set (DATASET4). All 
members on DATASET2 are lost when the data set is deleted. 
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• select specifies the members to be selected from the input data sets 

(DATASET6 and DATASET2) to be copied to the output data set (DATASET4). 

The temporary spill data sets may or may not be opened, depending on the 
amount of main storage available; therefore, it is suggested that the SYSUT3 and 
SYSUT4 DD statements always appear in the job stream. 



In this example, two members (A and B) are to be selected from two input 
partitioned data sets (DATASET5 and DATASET6) to be copied to an existing 
output partitioned data set (DATASETi). Member B is to replace an identically 
named member that already exists on the output data set. Figure 6-6 shows the 
input and output data sets before and after processing. 



The example follows: 



//COPY 


JOB 


//JOBSTEP 


EXEC 


//SYSPRINT 


DD 


//INOUT1 


DD 


// DISP=( OLD, KEEP) 


//INOUT6 


DD 


// DISP^OLD 


//INOUT5 


DD 


// DISP=( OLD, KEEP) 


//SYSUT3 


DD 


//SYSUT4 


DD 


//SYSIN 


DD 


COPYOPER 


COPY 



SELECT 



06#990,MCEWAN 

PGM=IEBCOPY 

SYSOUT=A 

DSNAME-DATASET1 ,UNIT=2314, VOL=SER=1 11112, 

DSNAME=DATASET6,UNIT=3330,VOL=SER=1 11115, 

DSNAME=DATASET5 , UNIT=2 3 1 4 , VOL=SER= 111116, 

UNIT=2314,SPACE=(TRK,( 1 ) ) 
UNIT=2 3 1 4 , SPACE=( TRK , ( 1 ) ) 
* 

OUTDD=INOUT1 
INDD=INOUT5 , INOUT6 
MEMBER=( (B, ,R),A) 



/* 

The control statements are discussed below: 

• [NOUTl DD defines a partitioned data set (DATASETI). This data set resides on 
a 2314 volume and contains three members (A, B, and F). 

• INOUT6 DD defines a partitioned data set (DATASET6). This data set resides 
on a 3330 volume and contains three members (B, C, and D). 

• INOUT5 DD defines a partitioned data set (DATASET5). This data set resides on 
a 2314 volume and contains two members (A and C). 

• SYSUT3 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 

• SYSUT4 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 

• SYSIN DD defines the control data set, which follows in the input stream. The 
data set contains a COPY statement, an INDD statement, and a SELECT 
statement. 

• COPY indicates the start of the copy operation. The presence of a SELECT 
statement causes a selective copy. The OUTDD parameter specifies INOUT1 as 
the DD statement for the output data set (DATASETI). 
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Figure 6-6. Selective Copy with "Replace" Specified on the Member Level 

• INDD specifies INOUT5 as the DD statement for the first input data set 
(DATASET5) to be processed and INOUT6 as the DD statement for the second 
input data set (DATASET6) to be processed. Processing occurs, as follows: (1) 
selected members are searched for on DATASET5, (2) member A is found, but 
is not copied to the output data set because it already exists on DATASET2 and 
the replace option is not specified, (3) selected members not found on 
DATASET5 are searched for on DATASET6, and (4) member B is found and 
copied to the output data set (DATASETl), even though a member named B 
already exists on the output data set, because the replace option is specified 
for member B on the member level. The pointer in the output data set 
directory is changed to point to the new (copied) member B; thus, the space 
occupied by the old member B is unused. 

• SELECT specifies the members to be selected from the input data sets 
(DATASET5 and DATASET6) to be copied to the output data set (DATASETl). 

The temporary spill data sets may or may not be opened, depending on the 
amount of main storage available; therefore, it is suggested that the SYSUT3 and 
SYSUT4 DD statements always appear in the job stream. 



In this example, two members (A and B) are to be selected from two input 
partitioned data sets (DATASET5 and DATASET6) to be copied to an existing 
output partitioned data set (DATASETl). All members found on DATASET5 are to 
replace identically named members on DATASETl. Figure 6-7 shows the input 
and output data sets before and after processing. 
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Figure 6-7. Selective Copy with "Replace" Specified on the Data Set Level 

The example follows: 



//COPY JOB 

//JOBSTEP EXEC 

//SYSPRINT DD 

//INOUT1 DD 

// DISP=( OLD, KEEP 

//INOUT5 DD 

// DISP=( OLD, DELETE 



//INOUT6 


DD 


// DISP=( OLD, KEEP 


//SYSUT3 


DD 


//SYSUT4 


DD 


//SYSIN 


DD 


COPYOPER 


COPY 




SELECT 



/* 



06#990,MCEWAN 

PGM=IEBCOPY 

SYSOUT=A 

DSNAME=DATASET1 , UNIT=3330 , VOL=SER=1 11112, 

DSNAME=DATASET5 , UNIT=23 1 4 , VOL=SER= 111114, 
) 
DSNAME=DATASET6,UNIT=2305,VOL=SER=1 11115, 

UNIT=2314,SPACE=(TRK, ( 1 ) ) 

UNIT=2314,SPACE=(TRK, ( 1 ) ) 
* 

OUTDD=INOUT1 

INDD-( ( INOUT5 , R ) , INOUT6 ) 

MEMBER=(A,B) 



The control statements are discussed below: 

• INOUT1 DD defines a partitioned data set (DATASET1). This data set resides on 
a 3330 volume and contains three members (A, B, and F). 

• INPUTS DD defines a partitioned data set (DATASET5). This data set contains 
two members (A and C) and resides on a 2314 volume. This data set is to be 
deleted when processing is completed. 

• INOUT6 DD defines a partitioned data set (DATASET6). This data set contains 
three members (B, C, and D) and resides on a 2305 volume. 
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• SYSUT3 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 

• SYSUT4 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 

• SYSIN DD defines the control data set, which follows in the input stream. The 
data set contains a COPY statement, an INDD statement, and a SELECT 
statement. 

• COPY indicates the start of the copy operation. The presence of a SELECT 
statement causes a selective copy. The OUTDD operand specifies INOUTl as 
the DD statement for the output data set (dataseti). 

• INDD specifies INOUT5 as the DD statement for the first input data set 
(DATASET5) to be processed and INOUT6 as the statement for the second 
input data set (DATASET6) to be processed. Processing occurs, as follows: (I) 
selected members are searched for on DATASET5, (2) member A is found and 
copied to the output data set (DATASETI) because the replace option was 
specified on the data set level for DATASET5, (3) member B, which was not 
found on DATASET5 is searched for and found on DATASET6, (4) member B is 
not copied because DATASETI already contains a member called member B 
and the replace option is not specified for DATASET6. The pointer in the 
output data set directory is changed to point to the new (copied) member A; 
thus, the space occupied by the old member A is unused. 

• SELECT specifies the members to be selected from the input data sets 
(DATASET5 and DATASET6) to be copied to the output data set (DATASETI). 

The temporary spill data sets may or may not be opened, depending on the 
amount of main storage available; therefore, it is suggested that the SYSUT3 and 
SYSUT4 DD statements always appear in the job stream. 



In this example, four members (A, B, c, and D) are to be selected from an input 
partitioned data set (DATASET6) to be copied to an existing output partitioned 
data set (DATASET3). Member B is to be renamed H; member C is to be renamed 
J; and member D is to be renamed K. In addition, member C (renamed J) is to 
replace the identically named member (J) on the output partitioned data set. 
Figure 6-8 shows the input and output data sets before and after processing. 

The example follows: 

//COPY JOB #990,MCEWAN 
//JOBSTEP EXEC PGM=IEBCOPY 
//SYSPRINT DD SYSOUT=A 

//INOUT3 DD DSNAME=DATASET3,UNIT=2314,VOL=SER=1 1 1 1 14, 
// DISP=( OLD, KEEP) 

//INOUT6 DD DSNAME=DATASET6,UNIT=2314,VOL=SER=1 1 1 1 17, 
// DISP=( OLD, DELETE) 

//SYSUT3 DD UNIT=2314,SPACE=(TRK,( 1 ) ) 
//SYSUT4 DD UNIT=2314,SPACE=(TRK, ( 1 ) ) 
//SYSIN DD * 
COPYOPER COPY OUTDD=INOUT3 

INDD=INOUT6 
SELECT MEMBER=( (B,H),(C,J,R),A,(D,K)) 
/* 
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Figure 6-8. Renaming Selected Members Using IEBCOPY 
The control statements are discussed below: 

• INOUT3 DD defines a partitioned data set (DATASET3). This data set contains 
four members (D, G, H, and J) and resides on a 2314 volume. 

• INOUT6 DD defines a partitioned data set (DATASET6). This data set contains 
three members (B, C, and D) and resides on a 2314 volume, DATASET6 is to 
be deleted when processing is completed; thus, all members on this data set 
are lost. 

• SYSUT3 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 

• SYSUT4 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 

• SYSIN DD defines the control data set, which follows in the input stream. The 
data set contains a COPY statement, an INDD statement, and a SELECT 
statement. 

• COPY indicates the start of the copy operation. The presence of a SELECT 
statement causes a selective copy. The OUTDD parameter specifies INOUT3 as 
the DD statement for the output data set (DATASET3). 
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• indd specifies INOUT6 as the DD statement for the input data set 
(DATASET6). Processing occurs, as follows: (1) selected members are searched 
for on DATASET6, (2) member B is found, but is not copied to DATASET3 
because its intended new name (H) is identical to the name of a member (H), 
which already exists on the output data set, and replace is not specified, (3) 
member C is found and copied to the output data set (DATASET3), although its 
new name (J) is identical to the name of a member (J), which already exists on 
the output data set, because the replace option is specified for the renamed 
member, and (4) member D is copied onto the output data set (DATASET3) 
because its new name (K) does not already exist there. 

• SELECT specifies the members to be selected from the input data set 
(DATASET6) to be copied to the output data set (DATASET3). 

The temporary spill data sets may or may not be opened, depending on the 
amount of main storage available; therefore, it is suggested that the SYSUT3 and 
SYSUT4 DD statements always appear in the job stream. 



In this example, five members (A, B, C, J, and L) are to be excluded from the 
copy operation when each of the input partitioned data sets (DATASETl, 
DATASET3, and DATASET6) is processed. In addition, replace is specified for the 
last input partitioned data set (DATASET6) to be processed; thus, with the 
exception of the members specified on the EXCLUDE statement, all members on 
DATASET6 will replace any identically named members on the output partitioned 
data set (DATASET4). Figure 6-9 shows the input and output data sets before and 
after processing. 



Output 
DATASET4 






wm* 






a&fc 



z^i*].isL&?' 



Before 

copy 

operation 



Copy repggng 
member 




Figure 6-9. Exclusive Copy with "Replace" Specified for One Input Partitioned Daita Set 
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The example follows: 

//COPY JOB 06#990,MCEWAN 

//JOBSTEP EXEC PGM=IEBCOPY 

//SYSPRINT DD SYSOUT=A 

//INOUT1 DD DSNAME=DATASET1 , UNIT=23 1 4 , VOL=SER=1 1 1 1 12, 

// DISP=( OLD, KEEP) 

//INOUT3 DD DSNAME=DATASET3 , UNIT=23 1 4 , VOL=SER=1 11114, 

// DISP=OLD 

//INOUT4 DD DSNAME=DATASET4,UNIT=2314,VOL=SER=1 1 1 1 15, 

// DISP=( NEW, KEEP ) , SPACE=( TRK , ( 3,1,2) ) ,DCB=( LRECL=1 00, 

// RECFM=FB / BLKSIZE=400) 

//INOUT6 DD DSNAME=DATASET6,UNIT=2314,VOL=SER=1 11116, 

// DISP=OLD 

//SYSUT3 DD UNIT=2314,SPACE=(TRK,( 1 ) ) 

//SYSUT4 DD UNIT=2314,SPACE=(TRK, ( 1 ) ) 

//SYSIN DD * 

COPYOPER COPY OUTDD=INOUT4,INDD=INOUT1 ,INOUT3,( TNOUT6,R) 

EXCLUDE MEMBER=A,J,B,L,C 
/* 

The control statements are discussed below: 

• INOUTI DD defines a partitioned data set (DATASET1). This data set contains 
three members (A, B, and F) and resides on a 2314 volume. The record format 
is fixed blocked with a logical record length of 100 bytes and a block size of 
400 bytes. 

• INOUT3 DD defines a partitioned data set (DATASET3), which resides on a 
2314 volume. This data set contains four members (D, G, H, and J) in fixed 
blocked format with a logical record length of 100 bytes and a block size of 
600 bytes. 

• INOUT4 DD defines a new partitioned data set (DATASET4). Five tracks are 
allocated for the copied members on a 2314 volume. Two blocks are allocated 
for directory entries. In addition records are to be copied to this data set in 
fixed blocked format with a logical record length of 100 bytes and a block 
size of 400 bytes. 

• INOUT6 DD defines a partitioned data set (DATASET6). This data set contains 
three members (B, C, and D) in fixed format. The records have a logical record 
length of 100 bytes and a block size of 100 bytes. This data set resides on a 
2314 volume. 

• SYSUT3 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 

• SYSUT4 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 

• SYSIN DD defines the control data set, which follows in the input stream. The 
data set contains a COPY statement and an EXCLUDE statement. 
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• COPY indicates the start of the copy operation. The presence of an EXCLUDE 
statement causes an exclusive copy. The OUTDD parameter specifies INOUT4 as 
the DD statement for the output data set (DATASET4). The INDD parameter 
specifies INOUT1 as the DD statement for the first input data set (DATASET1) 
to be processed, INOUT3 as the DD statement for the second input data set 
(DATASET3) to be processed, and INOUT6 as the DD statement for the last 
input data set (DATASET6) to be processed. Processing occurs, as follows: (1) 
member F, which is not named on the EXCLUDE statement, is copied from 
DATASETl, (2) members D, G, and H, which are not named on the EXCLUDE 
statement, are copied from DATASET3, and (3) member D is copied from 
DATASET6 because the replace option is specified for nonexcluded members. 
The pointer in the output data set directory is changed to point at the new 
(copied) member D; thus, the space occupied by the old member D (copied 
from DATASET3) is unused. 

• EXCLUDE specifies the members to be excluded from the copy operation. The 
named members are excluded from all of the input partitioned data sets 
specified in the copy operation. 

The temporary spill data sets may or may not be opened, depending on the 
amount of main storage available; therefore, it is suggested that the SYSUT3 and 
SYSUT4 DD statements always appear in the job stream. 



In this example, a partitioned data set is to be unloaded to a tape volume to 
create a backup copy of the data set. If this step is successful, the partitioned 
data set is to be compressed in place. 

The example follows: 

//SAVE JOB 123456, 'name' ,MSGLEVEL=( 1,1) 

//STEP1 EXEC PGM=IEBCOPY 

//SYSPRINT DD SYSOUT=A 

//INPDS DD DSNAME=PARTPDS,UNIT=2314,VOL=SER=PCP001 , 

// DISP=OLD 

//BACKUP DD DSNAME=SAVDATA,UNIT=2400,VOL=SER=TAPE03, 

// DISP=( NEW, KEEP ), LABEL=( , SL ) 

//SYSUT3 DD DSNAME=TEMP1 , UNIT=23 1 4 , VOL=SER=1 1 1 1 1 1 , 

// DISP=( NEW, DELETE ),SPACE=( 80, ( 60,45 ) ) 

//SYSIN DD * 

COPY OUTDD=BACKUP,INDD=INPDS 

/* 

//STEP2 EXEC PGM=IEBCOPY , COND=( , NE ) , 

// PARM='SIZE=99999999K' 

//SYSPRINT DD SYSOUT=A 

//COMPDS DD DSNAME=PARTPDS,UNIT=2314,DISP=OLD, 

// VOL=SER=PCP001 

//SYSUT3 DD DSNAME=TEMPA,UNIT=2314,VOL=SER=1 1 1 1 1 1 , 

// DISP=( NEW, DELETE ),SPACE=( 80, ( 60,45 ) ) 

//SYSUT4 DD DSNAME=TEMPB,UNIT=2314,VOL=SER=1 1 1 1 1 1 , 

// SPACE=( 256,(15,1)), DCB=KEYLEN=8 

//SYSIN DD * 

COPY OUTDD=COMPDS , INDD=COMPDS 
/* 

The control statements are discussed below: 

• INPDS DD defines a partitioned data set (PARTPDS) that resides on a 2314 
volume and has 700 members. The number of members is used to calculate 
the space allocation on SYSUT3. 

• BACKUP DD defines a sequential data set to hold PARTPDS in unloaded form. 
Block size information can optionally be added; this data set must be new. 
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• SYSUT3 DD defines the temporary spill data set. 

• SYSIN DD defines the control data set, which follows in the input stream. The 
data set contains a COPY statement. 

• COPY marks the beginning of the unload operation; the absence of an 
exclude or SELECT statement causes the entire partitioned data set 
(INDD=INPDS) to be unloaded to a sequential data set (OUTDD=BACKUP). 

• The second EXEC statement marks the beginning of the compress-in-place 
operation. The SIZE parameter indicates that the buffers are to be as large as 
possible. The COND parameter indicates that the compress-in-place is to be 
performed only if the unload operation was successful. 

• COMPDS DD defines a partitioned data set (partpds) that contains 700 
members and resides on a 2314 volume. 

• SYSUT3 DD defines the temporary spill data set to be used if there is not 
enough space in main storage for the input data set's directory entries. 

• SYSUT4 DD defines the temporary spill data set to be used if there is not 
enough space in main storage for the output partitioned data set's directory 
blocks. 

• SYSIN DD defines the control data set, which follows in the input stream. The 
data set contains a COPY statement. 

• COPY marks the beginning of the copy operation. The absence of a SELECT or 
EXCLUDE statement causes a default to a full copy. Because the same DD 
statement is specified for both the indd and OUTDD operands, the data set is 
compressed in place. 

The temporary spill data sets may or may not be opened, depending on the 
amount of main storage available; therefore, it is suggested that the SYSUT3 and 
SYSUT4 DD statements always appear in the job stream. Note, however, that the 
SYSUT4 data set is never used for an unload operation. 

Note: For an unload operation, only one INDD data set may be specified for one 
OUTDD data set. 



In this example, two input partitioned data sets (DATASET5 and DATASET6) are 
to be copied to an existing output partitioned data set (DATASET1). In addition, 
all members on DATASET6 are to be copied; members on the output data set that 
have the same names as the copied members are replaced. After DATASET6 is 
processed, the output data set (DATASETl) is to be compressed in place. Figure 
6-10 shows the input and output data sets before and after processing. 
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Figure 6-10. Compress-in-Place Following Full Copy with "Replace" Specified 

The example follows: 

//COPY JOB 06#990,MCEWAN 

//JOBSTEP EXEC PGM=IEBCOPY 

//SYSPRINT DD SYSOUT=A 

//INOUT1 DD DSNAME=DATASET1 , UNIT=23 1 4 , VOL=SER=1 1 1 1 12, 

// DISP=( OLD, KEEP) 

//INOUT5 DD DSNAME=DATASET5,UNIT=3330,VOL=SER=1 1 1 1 14, 

// DISP=OLD 

//INOUT6 DD DSNAME=DATASET6,UNIT=3330,VOL=SER=1 1 1 1 15, 

// DISP=( OLD, KEEP) 

//SYSUT3 DD UNIT=2314,SPACE=(TRK, ( 1 ) ) 

//SYSUT4 DD UNIT=2314,SPACE=(TRK,( 1 ) ) 

//SYSIN DD * 

COPYOPER COPY OUTDD=INOUT1 

INDD=INOUT5 , ( INOUT6 , R ) , INOUT1 
/* 

The control statements are discussed below: 

• INOUT1 DD defines a partitioned data set (DATASETl). This data set contains 
three members (A, B, and F) and resides on a 2314 volume. 

• INOUT5 DD defines a partitioned data set (DATASET5). This data set contains 
two members (A and C) and resides on a 3330 volume. 
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• INOUT6 DD defines a partitioned data set (DATASET6). This data set contains 
three members (B, C, and D) and resides on a 3330 volume. 

• SYSUT3 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 

• SYSUT4 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 

• sysin dd defines the control data set, which follows in the input stream. The 
data set contains a COPY statement and an INDD statement. 

• COPY indicates the start of the copy operation. The OUTDD operand specifies 
INOUT1 as the DD statement for the output data set (DATASETl). The absence 
of a SELECT or EXCLUDE statement causes a default to a full copy. 

• indd specifies INOUT5 as the DD statement for the first input data set 
(DATASET5) to be processed. It then specifies INOUT6 as the DD statement for 
the second input data set (DATASET6) to be processed; in addition, the replace 
option is specified for all members copied from DATASET6. Finally, it specifies 
INOUT1 as the DD statement for the last input data set (DATASETD to be 
processed; this causes a compress-in-place of DATASETl because it is also 
specified as the output data set. Processing occurs, as follows: (1) member A 
is not copied from DATASET5 onto the output data set (DATASETl) because it 
already exists on DATASETl and the replace option was not specified for 
DATASET5, (2) member C is copied from DATASET5 to the output data set 
(DATASETl), occupying the first available space, and (3) all members are 
copied from DATASET6 to the output data set (DATASETl), immediately 
following the last member. Members B and C are copied even though the 
output data set already contains members with the same names because the 
replace option is specified on the data set level. The pointers in the output 
data set directory are changed to point to the new members B and C; thus, the 
space occupied by the old members B and C is unused. The members currently 
on DATASETl are compressed in place, thereby eliminating embedded unused 
space. 

The temporary spill data sets may or may not be opened, depending on the 
amount of main storage available; therefore, it is suggested that the SYSUT3 and 
SYSUT4 dd statements always appear in the job stream. 



In this example, members are to be selected, excluded, and copied from input 
partitioned data sets onto an output partitioned data set. This example is 
designed to illustrate multiple copy operations. Figure 6-11 shows the input and 
output data sets before and after processing. 
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Figure 6-11. Multiple Copy Operations/Copy Steps 



The example follows: 



//COPY 


JOB 


//JOBSTEP 


EXEC 


//SYSPRINT 


DD 


//INOUTA 


DD 


// DISP=OLD 


//INOUTB 


DD 


// DISP=( OLD, KEEP ) 


//INOUTC 


DD 


// DISP=( OLD, KEEP) 


//INOUTD 


DD 


// DISP=OLD 


//INOUTE 


DD 


// DISP=OLD 


//INOUTX 


DD 


// DISP=( NEW, KEEP) 


//SYSUT3 


DD 


//SYSUT4 


DD 


//SYSIN 


DD 


COPERST1 


COPY 




COPY 




COPY 




EXCLUDE 




SELECT 



06#990,MCEWAN 

PGM=IEBCOPY 

SYSOUT=A 

DSNAME=DATASETA , UNIT=2 3 1 4 , VOL=SER= 1 

DSNAME=DATASETB , UNIT=23 1 4 , VOL=SER= 1 

DSNAME=DATASETC , UNIT=23 1 4 , VOL=SER= 1 

DSNAME-DATASETD , UNIT=2 3 1 4 , VOL=SER= 1 

DSNAME=DATASETE , UNIT=23 1 4 , VOL=SER= 1 

DSNAME=DATASETX,UNIT=2314,VOL=SER=1 
SPACE=(TRK, (3,1,2)) 
UNIT=2314,SPACE=(TRK,( 1 ) ) 
UNIT=2314,SPACE=(TRK,( 1 ) ) 
* 

0=INOUTX, I=INOUTA 

OUTDD=INOUTA, INDD=INOUTA 

INDD=INOUTB 

0=INOUTA 

INDD=INOUTD 

MEMBER=MM 

INDD=INOUTC 

MEMBER=( (ML,MD,R) ) 

INDD=INOUTE 



1 13, 
115, 
1 14, 
116, 
117, 
1 12, 



/* 



The control statements are discussed below: 

INOUTA DD defines a partitioned data (DATASETA). This data set contains 
eight members (MA, MB, MC, MD, ME, MF, MG, and MH) and resides on a 
2314 volume. 

INOUTB DD defines a partitioned data set (DATASETB). This data set resides 
on a 23 1 4 volume and contains two members (MA and MJ). 

INOUTC DD defines a partitioned data set (DATASETC), which resides on a 
2314 volume. The data set contains four members (MF, ML, MM, and MN). 

INOUTD dd defines a partitioned data set (DATASETD). This data set resides 
on a 2314 volume and contains two members (MM and MP). 

INOUTE dd defines a partitioned data set (DATASETE). This data set contains 
four members (MD, ME, MF, and MT) and resides on a 2314 volume. 

INOUTX DD defines a partitioned data set (DATASETX). This data set is new 
and is to be kept after the copy operation. Five tracks are allocated for the 
data set on a 2314 volume. Two blocks are allocated for directory entries. 

SYSUT3 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 

SYSUT4 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 

SYSIN dd defines the control data set, which follows in the input stream. The 
data set contains two COPY statements, several INDD statements, a SELECT 
statement, and an EXCLUDE statement. 

The first COPY statement indicates the start of the first copy operation. This 
Copy operation is done to create a backup copy of DATASETA, which is 
subsequently compressed in place. 
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• The second COPY statement indicates the start of another copy operation. The 
absence of a SELECT or EXCLUDE statement causes a default to a full copy; 
however, the same DD statement, INOUTA, is specified for both the INDD and 
OUTDD parameters, causing a compress-in-place of the specified data set. 

• INDD specifies INOUTB as the DD statement for the input data set 
(DATASETB) to be copied. Only member MJ is copied because member MA 
already exists on the output data set. 

• The third COPY statement indicates the start of the third copy operation. The 
OUTDD parameter specifies INOUTA as the DD statement for the output data 
set (DATASETA). This copy operation contains more than one copy step. 

• The first INDD statement specifies INOUTD as the DD statement for the first 
input data set (DATASETD) to be processed. Only member MP is copied to the 
output data set (DATASETA) because member MM is specified on the 
EXCLUDE statement. 

• EXCLUDE specifies" the member to be excluded from the first copy step within 
this copy operation. 

• The second INDD statement marks the beginning of the second copy step for 
this copy operation and specifies INOUTC as the DD statement for the second 
input data set (DATASETC) to be processed. Member ML is searched for, 
found, and copied to the output data set (DATASETA). Member ML is copied 
even though its new name (MD) is identical to the name of a member (MD) 
that already exists on the output data set, because the replace option is 
specified for the renamed member. 

• SELECT specifies the member to be selected from the input data set 
(DATASETC) to be copied to the output partitioned data set. 

• The third INDD statement marks the beginning of the third copy step for this 
copy operation and specifies INOUTE as the DD statement for the last data set 
(DATASETE) to be copied. Only member MT is copied because the other 
members already exist on the output data set. Because the INDD statement is 
not followed by an EXCLUDE or SELECT statement, a full copy is performed. 

The temporary spill data sets may or may not be opened, depending on the 
amount of main storage available; therefore, it is suggested that the SYSUT3 and 
SYSUT4 DD statements always appear in the job stream. 

The output data set is compressed in place first to save space because it is known 
that it contains embedded, unused space. 



In this example, members are to be selected, excluded, and copied from input 
partitioned data sets to an output partitioned data set. This example is designed 
to illustrate multiple copy operations. Figure 6-12 shows the input and output 
data sets before and after processing. 
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First copy operation 








Second copy operation 



Third copy operation 
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Member MF 
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Before 
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Figure 6-12. Multiple Copy Operations/Copy Steps Within a Job Step 
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The example follows: 



//COPY 


JOB 


//JOBSTEP 


EXEC 


//SYSPRINT 


DD 


//INOUTA 


DD 


// DISP=OLD 


//INOUTB 


DD 


// DISP=( OLD, KEEP) 


//INOUTC 


DD 


// DISP=( OLD, KEEP) 


//INOUTD 


DD 


// UNIT=2314 


//INOUTE 


DD 


// UNIT=2314 


//SYSUT3 


DD 


//SYSUT4 


DD 


//SYSIN 


DD 




COPY 




SELECT 




EXCLUDE 




COPY 




COPY 




SELECT 



06#990,MCEWAN 

PGM=IEBCOPY 

SYSQUT=A 

DSNAME=DATASETA,UNIT=2314,VOL=SER=1 11113, 

DSNAME=DATASETB,VOL=SER=1 11 1 1 5 , UNIT=23 1 4 , 

DSNAME=DATASETC , VOL=SER= 1 1 1 1 1 4 , UNIT=2 3 1 4 , 

DSNAME=DATASETD,VOL=SER=1 1 1 1 1 6,DISP=OLD, 

DSNAME=DATASETE,VOL=SER=1 1 1 1 17,DISP=OLD, 

UNIT=23 1 4 , SPACE=( TRK, ( 1 ) ) 
UNIT=23 1 4 , SPACE=( TRK, ( 1 ) ) 
* 

OUTDD=INOUTA 
INDD=INOUTE 
MEMBER=MA,MJ 
INDD=INOUTC 
MEMBER=MM,MN 
0=INOUTB, INDD=INOUTD 
I = ( ( INOUTC , R ) , INOUTB ) 
0=INOUTD,I=( ( INOUTB, R) ) 
MEMBER=MM 



/* 



The control statements are discussed below: 

INOUTA DD defines a partitioned data set (DATASETA). This data set contains 
three members (MA, MB, and MD) and resides on a 2314 volume. 

INOUTB DD defines a partitioned data set (DATASETB). This data set resides 
on a 2314 volume and contains two members (MA and MJ). 

INOUTC DD defines a partitioned data set (DATASETC), which resides on a 
2314 volume. This data set contains four members (MF, ML, MM, and MN). 

INOUTD DD defines a partitioned data set (DATASETD). This data set resides 
on a 2314 volume and contains two members (MM. and MP). 

INOUTE DD defines a partitioned data set (DATASETE), which resides on a 
2314 volume. This data set contains three members (MA, MJ and MK). 

SYSUT3 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 

SYSUT4 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 

SYSIN DD defines the control data set, which follows in the input stream. The 
data set contains three COPY statements, SELECT and EXCLUDE statements, 
and several INDD statements. 

The first COPY statement indicates the start of a copy operation. The OUTDD 
operand specifies INOUTA as the DD statement for the output data set 
(DATASETA). 

The first INDD statement specifies INOUTE as the DD statement for the first 
input data set (DATASETE) to be processed. Processing occurs, as follows: (1) 
member MA is searched for and found, but is not copied because the replace 
option is not specified, and (2) member MJ is searched for, found, and copied 
to the output data set. Members are not searched for again after they are 
found. 
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• SELECT specifies the members (MA and MJ) to be selected from the input data 
set (DATASETE) to be copied. 

• The second INDD statement marks the end of the first copy step and the 
beginning of the second copy step within the first copy operation. It specifies 
INOUTC as the DD statement for the second input data set (DATASETC) to be 
processed. Members MF and ML, which are not named on the EXCLUDE 
statement, are copied because neither exists on the output data set. 

• exclude specifies the members (MM and MN) to be excluded from the second 
copy operation. 

• The second COPY statement indicates the start of another copy operation. The 
absence of a SELECT or exclude statement causes a default to a full copy. 
The o (OUTDD) parameter specifies INOUTB as the output data set 
(DATASETB). The INDD parameter specifies INOUTD as the first input data set 
(DATASETD) to be processed. Members MP and MM are copied to the output 
data set. 

• INDD(I) specifies INOUTC as the DD statement for the second input data set 
(DATASETC) and INOUTB as the DD statement for the third input data set 
(DATASETB) to be processed. Members MF, ML, MM, and MN are copied from 
DATASETC. Member MM is copied, although it already exists on the output 
partitioned data sets, because the replace option is specified. Because 
DATASETB is also the data set specified in the OUTDD parameter, a 
compress-in-place takes place. (The pointer in the output data set directory is 
changed to point to the new (copied) member MM; thus the space occupied by 
the replaced member MM is embedded, unused space.) 

• The third COPY statement indicates the start of another copy operation. The o 
(OUTDD) parameter specifies INOUTD as the DD statement for the output data 
set (DATASETD). The I (INDD) parameter specifies INOUTB as the DD 
statement for the input data set (DATASETB). 

• SELECT specifies the member (MM) to be selected from the input partitioned 
data set (DATASETB) to be copied. The replace option is specified on the data 
set level. 

The temporary spill data sets may or may not be opened, depending on the 
amount of main storage available; therefore, it is suggested that the SYSUT3 and 
SYSUT4 DD statements always appear in the job stream. 

Data sets used as input data sets in one copy operation can be used as output 
data sets in another copy operation, and vice versa. 



In this example, a partitioned data set (SYS1.LINKLIB) is to be unloaded to a tape 
volume. 

The example follows: 

//UNLOAD JOB 246803, 'name' ,MSGLEVEL=( 1,1) 

//STEP1 EXEC PGM=IEBCOPY,PARM='SIZE=100K' 

//SYSPRINT DD SYSOUT=A 

//INPDS DD DSNAME=SYS1 . LINKLIB, UNIT=23 1 4 ,DISP=SHR, 

// VOL=SER=666666 

//OUTTAPE DD DSNAME=LINKLIB, UNIT=2400 , VOL=SER=TAPE00 , 

// LABEL- ( ,SL),DISP=( NEW, KEEP) 

//SYSUT3 DD DSN=TEMP1 , UNIT=23 1 4 , VOL=SER=1 1 1 1 1 1 , 

// DISP=( NEW, DELETE ),SPACE=( 80, ( 60,45 ) ) 

//SYSIN DD * 

COPY OUTDD=OUTTAPE 
INDD=INPDS 
/* 



6-38 OS/VS Utilities 



IEBCOPY Example 14 



The control statements are discussed below: 

• EXEC specifies the execution of IEBCOPY. The PARM parameter specifies the 
size of the input/output buffer to be used. 

• inpds DD defines a partitioned data set (SYSI.LINKLIB), which resides on a 
2314 volume. This data set has 700 members; the number of members is used 
to calculate the space allocation for SYSUT3. 

• OUTTAPE DD defines a sequential data set to which SYSI.LINKLIB is to be 
unloaded. The unloaded data set is named LINKLIB. This data set must be new; 
if a tape volume is used, it can be standard labeled or unlabeled. 

• SYSUT3 DD defines a temporary spill data set on a 2314 volume. This data set 
is used if there is not enough space in main storage for the input partitioned 
data set's directory entries. This data set may or may not be opened 
depending on the amount of main storage available; therefore, it is suggested 
that the statement always appear in the job stream. 

• SYSIN DD defines the control data set, which follows in the input stream. The 
data set contains a COPY and INDD statement. 

• COPY indicates the start of an unload operation because the OUTDD parameter 
refers to OUTTAPE DD, which specifies a sequential output data set. Because 
of the absence of an EXCLUDE or SELECT statement, the entire data set is 
unloaded. 

• INDD refers to INPDS DD, which defines the input partitioned data set to be 
unloaded. Note that for an unload operation, only one INDD data set may be 
specified for each OUTDD data set. 

The SYSUT4 data set is never used for an unload operation. The SYSUT3 data set 
for an unload operation is used under the same conditions as it is used for a copy 
operation. 

Note: If too much space is allocated, the paging process slows down because the 
buffer areas are fixed. 



In this example, a sequential data set created by an IEBCOPY unload operation is 
to be loaded. 

The example follows: 

//LOAD JOB 246803, 'name' ,MSGLEVEL=( 1,1) 

//STEPA EXEC PGM=IEBCOPY,PARM='SIZE= 14588' 

//SYSPRINT DD SYSOUT=A 

//SEQIN DD DSNAME=UNLOADSET,UNIT=2400,LABEL=( ,SL), 

// VOL=SER=TAPE01 ,DISP=OLD 

//INOUT4 DD DSNAME=DATASET4,UNIT=2314,VOL=SER=231400, 

// DISP=( NEW, KEEP ) , SPACE=( CYL, ( 10,5,10)) 

//SYSUT3 DD DSN=TEMP1 ,UNIT=231 4 , VOL=SER=1 1 1 1 1 1 , 

// DISP=( NEW, DELETE ),SPACE=( 80, ( 15,1 ) ) 

//SYSIN DD * 

COPY OUTDD=INOUT4 , INDD=SEQIN 
/* 

The control statements are discussed below: 

• EXEC specifies the execution of IEBCOPY. The PARM parameter allocates two 
tracks on a 2314 volume. If less space is specified, two tracks are allocated 
because two tracks are the minimum required by IEBCOPY when the unloaded 
data set's block size does not exceed the track capacity. 
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• SEQIN DD defines a sequential data set that was previously unloaded by 
IEBCOPY, The data set contains 28 members in sequential organization. 

• INOUT4 DD defines a partitioned data set on a 2314 volume. This data set is 
to be kept after the load operation. Ten cylinders are allocated for the data 
set; ten blocks are allocated for directory entries. 

• SYSUT3 DD defines a temporary spill data set on a 2314 volume. This data set 
is used if there is not enough space in main storage for the input data set's 
directory entries. This data set may or may not be opened, depending on the 
amount of main storage available; therefore, it is suggested that the statement 
always appear in the job stream. Note that the space allocated for this data set 
is based on the number of members in the input data set. 

• SYSIN DD defines the control data set, which follows in the input stream. The 
data set contains a COPY statement. 

• COPY indicates the start of a load operation because the INDD parameter refers 
to SEQIN DD, which defines a sequential data set, and OUTDD refers to 
INOUT4 DD, which defines a direct access volume. 

Because the output data set in this example is new, the SYSUT4 data set is not 
needed. SYSUT4 should be specified, however, when the output data set is old. 

Note: Reblocking may be specified for the output partitioned data set. 



In this example, a partitioned data set is to be unloaded to a tape volume to 
create a backup copy of the data set. If the unload operation is successful, the 
partitioned data set is subsequently to be compressed in place. 

The example follows: 

//SAVE JOB 123456, 'name' ,MSGLEVEL=( 1 , 1 ) 

//STEP1 EXEC PGM=IEBCOPY 

//SYSPRINT DD SYSOUT=A 

//INPDS DD DSNAME=PARTPDS,UNIT=2314,DISP=OLD, 

// VOL=SER=PCP001 

//BACKUP DD DSNAME=SAVDATA,UNIT=2400,VOL=SER=TAPE03, 

// DISP=( NEW, KEEP ),LABEL=( , SL ) 

//SYSUT3 DD DSNAME=TEMP1 ,UNIT=23 1 4 , VOL=SER=1 1 1 1 1 1 , 

// DISP=( NEW, DELETE ) , SPACE=( 80 , ( 60 , 45 ) ) 

//SYSIN DD * 

COPY OUTDD=BACKUP,INDD=INPDS 

/* 

//STEP2 EXEC PGM=IEBCOPY,COND=( ,NE ) , PARM= ' SIZE=99999999K' 

//SYSPRINT DD SYSOUT=A 

//COMPDS DD DSNAME=PARTPDS,UNIT=2314,DISP=OLD, 

// VOL=SER=PCP001 

//SYSUT3 DD DSNAME=TEMPA,UNIT=2314,VOL=SER=1 1 1 1 1 1 , 

// DISP=( NEW, DELETE ),SPACE=( 80,(60,45 ) ) 

//SYSUT4 DD DSNAME=TEMPB,UNIT=2314,VOL=SER=1 1 1 1 1 1 , 

// DISP=( NEW, DELETE ),SPACE=( 256, ( 15, 1 ) ) ,-DCB=( KEYLEN=8 ) 

//SYSIN DD * 

COPY OUTDD=COMPDS , INDD=COMPDS 
/* 

The control statements are discussed below: 

• INPDS DD defines a partitioned data set (PARTPDS), which resides on a 2314 
volume. The data set contains 700 members; the number of members is used 
to calculate the space to be allocated for the SYSUT3 data set. 

• BACKUP DD defines a sequential data set to which PARTPDS is to be 
unloaded. This data set must be new; the tape can be unlabeled or standard 
labeled. 
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• The first SYSUT3 DD statement defines a temporary spill data set on a 2314 
volume. 

• The first SYSIN DD statement defines the control data set for the first job 
step. The data set contains a COPY statement. 

• The first COPY statement indicates the start of an unload operation because 
INDD refers to INPDS DD, which defines a partitioned data set, and OUTDD 
refers to BACKUP DD, which defines a sequential data set. Because of the 
absence of an EXCLUDE or SELECT statement, the entire data set is unloaded. 

• The second EXEC statement specifies in the COND parameter that this job step 
(a compress-in-place) is to be executed only if the first job step (unload) was 
successful. The PARM parameter specifies the largest possible buffer size. 

• COMPDS DD defines a partitioned data set (PARTPDS), which resides on a 
2314 volume. This data set contains 700 members. 

• The second SYSUT3 DD statement defines a temporary spill data set on a 2314 
volume for the second job step. 

• SYSUT4 DD defines a temporary spill data set on a 2314 volume. Note that 
SYSUT4 is specified for the load operation, but was not specified for the 
unload operation in the first job step. 

• The second SYSIN DD statement defines the control data set, which follows in 
the input stream, for the second job step. The data set contains a COPY 
statement. 

• COPY specifies a compress-in-place operation because INDD and OUTDD both 
refer to COMPDS DD, which defines a partitioned data set. 



In this example, members are to be selected, excluded, unloaded, loaded, and 
copied. Processing will occur, as follows: (1) unload, excluding members, (2) 
unload, selecting members, and (3) load and copy to merge members. 

The example follows: 

//COPY JOB 06#990, 'name' ,MSGLEVEL=( 1,1) 

//STEP EXEC PGM=IEBCOPY 

//SYSPRINT DD SYSOUT=A 

//PDS1 DD DSNAME=ACCOUNTA,UNIT=3330,VOL=SER=333000, 

// DISP=OLD 

//PDS2 DD DSNAME=ACCOUNTB,UNIT=3330,VOL=SER=333000, 

// DISP=OLD 

//SEQ1 DD DSNAME=SAVAC,UNIT=3330,VOL=SER=333000, 

// DISP=(NEW,KEEP),SPACE=(CYL,(5,2 ) ) 

//SEQ2 DD DSNAME=SAVACB , UNIT=2400 , VOL=SER=T0 1911, 

// DISP=( NEW, KEEP ),LABEL=( , SL ) 

//NEWUP DD DSNAME=NEWACC,UNIT=2400,VOL=SER=T01219, 

// DISP=OLD,LABEL=( , SL) 

//MERGE DD DSNAME=ACCUPDAT,UNIT=23 1 4 , VOL=SER=23 1400 , 

// DISP=OLD 

//SYSUT3 DD DSNAME=TEMP1 , VOL=SER=666666 , UNIT=23 14 , 

// DISP=( NEW, DELETE ),SPACE=( 80 , ( 1 , 1 ) ) 

//SYSUT4 DD DSNAME=TEMP2,VOL=SER=666666,UNIT=2314, 

// DISP=( NEW, DELETE ),SPACE=( 256, ( 1,1) ) ,DCB=( KEYLEN=8 ) 

//SYSIN DD * 

COPY OUTDD=SEQ1 ,INDD=PDS1 

EXCLUDE MEMBER=(D,C) 

COPY OUTDD=SEQ2,INDD=PDS2 

SELECT MEMBER=(A,K) 

COPY OUTDD=MERGE , INDD=( ( NEWUP , R ) , PDS 1 , PDS2 ) 

EXCLUDE MEMBER=A 
/* 
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The control statements are discussed below: 

PDSl DD defines a partitioned data set that contains six members (A, B, C, D, 
E, and F) and resides on a 3330 volume. 

PDS2 DD defines a partitioned data set that contains three members (A, K, and 
L) and resides on a 3330 volume. 

SEQl DD defines a new sequential data set on a 3330 volume. 

SEQ2 DD defines a new sequential data set on a 2400 volume. 

newup DD defines an old sequential data set that is the unloaded form of a 
partitioned data set that contains eight members (A, B, c, D, M, N, O, and P). 
It resides on a 2400 volume. 

MERGE DD defines a partitioned data set that contains six members (A, B, C, 
D, Q, and R) and resides on a 2314 volume. 

The first COPY statement indicates the start of the first unload operation. (The 
input data set is partitioned; the output data set is sequential) 

The first EXCLUDE statement specifies that members D and C are to be 
excluded from the unload operation specified by the preceding COPY 
statement. 

The second COPY statement indicates the start of the second unload operation. 
(The input data set is partitioned; the output data set is sequential.) 

The SELECT statement specifies that members A and K are to be included in 
the unload operation specified by the preceding COPY statement. 

The third COPY statement indicates the start of the copy and load operations. 
The replace option is specified for the NEWUP data set; therefore, members in 
this data set replace identically named members on the output data set. The 
first INDD data set is an unloaded data set that is to be loaded. The second 
and third INDD data sets are partitioned data sets that are to be copied. (The 
input data sets are sequential and partitioned; the output data set is 
partitioned.) 
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IBM-Supplied Patterns 



IEBDG is a data set utility used to provide a pattern of test data to be used as a 
programming debugging aid. (See "Introduction" for general data set utility 
information.) 

An output data set, containing records of any format, can be created through the 
use of utility control statements, with or without input data. An optional user exit 
is provided to pass control to a user routine to monitor each output record before 
it is written. Sequential, indexed sequential, and partitioned data sets can be used 
for input or output. 

To generate test data, the user constructs a pattern of data that he can analyze 
quickly for predictable results. Test data is generated through the use of utility 
control statements. 

When the user defines the contents of a field, he decides: 

• What type of pattern — IBM-supplied or user-supplied — he wishes to place 
initially in the defined field. 

• What action, if any, is to be performed to alter the contents of the field after 
it is selected for each output record. 



IBM supplies seven patterns: alphameric, alphabetic, zoned decimal, packed 
decimal, binary number, collating sequence, and random number. The user may 
choose one of them when he defines the contents of a field. All patterns except 
the binary and random number patterns repeat in a given field, provided thai: the 
defined field length is sufficient to permit repetition. For example, the alphabetic 
pattern is: 

ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFG. . . 

Table 7-1 shows the IBM-supplied patterns. 

Table 7-1. IBM-Supplied Patterns 



Type 


Expressed in 
Hexadecimal 




Expressed in 
Printable Characters 


Alphameric 


CI C2 . . .E9 FO. . 


.F9 


ABC ... Z ... 9 


Alphabetic 


CI C2 . . . E9 




ABC . . . Z 


Zoned Decimal 


FOFO . . . F0F1 




00 ... 01 


Packed Decimal 


0000 . . . 001C 
(Positive pattern) 
0000 . . . 001D 
(Negative pattern) 




Not applicable 


Binary Number 


00 ... 01 
(Positive pattern) 
FF . . . FF 
(Negative pattern) 




Not applicable 


Collating Sequence 


40 . . . F9 




fe*.<(+ I &!$*);-.-/,% 
A. . . Z0. . . 9 


Random Number 


Random hexadecimal digits 


Not applicable 



>?:#©'=" 



Note: A packed decimal or binary number is right aligned in the defined field. 
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User-Specified Pictures 



The user can specify a starting character when defining an alphameric, 
alphabetic, or collating-sequence field. For example, a ten-byte alphabetic field 
for which "H" is specified as the starting character would appear as: 

HIJKLMNOPQ 

The same ten-byte alphabetic field with no specified starting character would 
appear as: 

ABCDEFGHIJ 

The user can specify a mathematical sign when defining a packed decimal or 
binary field. If no sign is specified, the field is assumed to be positive. 



Instead of selecting an IBM-supplied pattern, the user can specify a picture to be 
placed in the defined field. The user can provide: 

• An EBCDIC character string. 

• A decimal number to be converted to packed decimal by IEBDG. 

• A decimal number to be converted to binary by IEBDG. 

When the user supplies a picture, he must specify a picture length that is equal to 
or less than the specified field length. An EBCDIC picture is left aligned in a 
defined field; a decimal number that is converted to packed decimal or to binary 
is right aligned in a defined field. 

The user can initially load (fill) a defined field with either an EBCDIC character 
or a hexadecimal digit. For example, the 10-byte picture "BADCFEHGJI" is to be 
placed in a 15-byte field. An EBCDIC "2" is to be used to pad the field. The 
result is BADCFEHGJI22222. (If no fill character is provided, the remaining bytes 
contain binary zeros.) Remember that the fill character, if specified, is written in 
each byte of the defined field prior to the inclusion of an IBM-supplied pattern or 
user-supplied picture. 



Modification of Selected Fields 



IEBDG can be used to change the contents of a field in a specified manner. One 
of eight actions can be selected to change a field after its inclusion in each 
applicable output record. These actions are ripple, shift left, shift right, truncate 
left, truncates right, fixed, roll, and wave. 

Figure 7-1 shows the effects of each of the actions on a six-byte alphabetic field. 
Note that the roll and wave actions are applicable only when a user pattern is 
supplied. In addition, the result of a ripple action depends on which type of 
pattern — IBM-supplied or user-supplied — is present. 
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Input and Output 



Ripple-user- 
supplied picture 


Ripple- IBM- 
supplied format 


Shift left 




Shift right 


A B C D E F 




A B C D E F 




A B C D E F 




A BC D E F 


B C D E F A 


B C D E F G 


BC D E F 


ABCDE 


C D E F A B 


C D E F G H 


C D E F 


A BC D 


D E F A B C 


D E F G H 1 


D E F 


ABC 


E F A B C D 


E F G H 1 J 


E F 


A B 


F A B C D E 
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Figure 7-1. iebdg Actions 

If no action is selected, or if the specified action is not compatible with the 
format, the fixed action is assumed by IEBDG. 



IEBDG uses the following input: 

• An input data set, which contains records that are to be used in the 
construction of an output data set or partitioned data set member. The input 
data sets are optional; that is, output records can be created entirely from 
utility control statements. 

• A control data set, which contains any number of sets of utility control 
statements. 

IEBDG produces the following output: 

• An output data set, which is the result of the IEBDG operation. One output 
data set is created by each set of utility control statements included in the job 
step. 

• A message data set, which contains informational messages, the contents of 
applicable utility control statements, and any error messages. 

Note that input and output data sets may be sequential, indexed sequential, or 
partitioned data set members. 

BDAM is not supported. 

IEBDG produces a return code to indicate the results of program execution. The 
return codes and their meanings are: 

• 00, which indicates successful completion. 

• 04, which indicates that a user routine returned a code of 16 to IEBDG. The 
job step is terminated at the user's request. 



I 
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08, which indicates that an error occurred while processing a set of utility 
control statements. No data is generated following the error. Processing 
continues normally with the next set of utility control statements, if any. 

12, which indicates that an error occurred while processing an input or output 
data set. The job step is terminated. 

16, which indicates that an error occurred from which recovery is not possible. 
The job step is terminated. 



Control 



IEBDG is controlled by job control statements and utility control statements. The 
job control statements are used to execute or invoke IEBDG and define the data 
sets used and produced by IEBDG. Utility control statements are used to control 
the functions of the program and to define the contents of the output records. 

Job Control Statements 

Table 7-2 shows the job control statements necessary for using IEBDG. 

Table 7-2. IEBDG Job Control Statements 

Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (PGM=IEBDG) or, if the job control statements 

reside in a procedure library, the procedure name. Additional information 
can be specified in the EXEC statement; see "PARM Information on the EXEC 
Statement" below. 

SYSPRINT DD Defines a sequential message data set. The data set can be written on a 
system output device, a tape volume, or a direct access volume. 

SYSIN DD Defines the control data set, which contains the utility control statements 

and, optionally, input records. The data set normally resides in the input 
stream; however, it can be defined as a sequential data set or as a member of 
a partitioned data set. 

seqinset DD Defines an optional sequential or indexed sequential data set used as input to 

IEBDG. The data set can reside on a tape volume or on a direct access 
volume. Any number of these statements (each having a ddname different 
from all other ddnames in the job step) can be included in the job step. Each 
DD statement is subsequently referred to by a DSD utility control statement. 

parinset DD Defines an optional input partitioned data set member residing on a direct 

access volume. Any number of these statements (each having a ddname 
different from all other ddnames in the job step) can be included in the job 
step. The "parinset" DD statement is referred to by a DSD utility control 
statement. 

seqout DD Defines an output (test) sequential or indexed sequential data set. Any 

number of "seqout" DD statements can be included per job step; however, 
only one "seqout" statement is applicable per set of utility control statements. 

parout DD Defines an optional output partitioned data set member to be created and 

placed on a direct access volume. Any number of "parout" DD statements 
(each DD statement referring to the same or to a different data set) can be 
included per job step; however, only one "parout" statement is applicable per 
set of utility control statements. 

The SYSPRINT data set and the SYSIN data set can have any blocking factor. 

Both input and output data sets can contain fixed, variable, or undefined records. 

Refer to OS/VS Data Management Services Guide, GC26-3783, for information on 
estimating space allocations. 

The "seqinset" DD statement can be entered: 

//seqinset DD DSNAME=setname,UNIT=xxxx,DISP=(OLD,KEEP), 
// VOLUME=SER=xxxxxx,LABEL=(.. .,...), 

// DCB=(applicable subparameters) 
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Restrictions 



The LABEL parameter is included only for a magnetic tape volume. If the input 
data set has an indexed sequential organization, DSORG=is should be coded in 
the DCB parameter. 

The "parinset" DD statement can be entered: 

//parinset DD DSNAME=setname(membername),UNIT=xxxx,DISP=(OLD, 
// KEEP),VOLUME=SER=xxxxxx, 

// DCB=(applicable subparameters) 

The "seqout" DD statement can be entered: 

//seqout DD DSNAME=setname, UNIT=xxxx, 

// DISP=(,KEEP),VOLUME=SER=xxxxxx, 

// DCB=(applicable subparameters) 

The LABEL parameter is included for magnetic tape; the SPACE parameter is 
included for direct access. 

The "parout" DD statement can be entered: 

//parout DD DSNAME=setname(membername),UNIT=xxxx, 

// DISP=(,KEEP),VOLUME=SER=xxxxxx,DCB=(applicable 

// subparameters),DISP=(,KEEP), 

// SPACE= (applicable subparameter) 

The SPACE parameter is included on the parout DD statement when creating the 
first member to be placed in a partitioned data set. 



• The DSORG subparameter must be included in the DCB subparameters if the 
input or output data set has an indexed sequential organization (DSORG=lS). If 
members of a partitioned data set are used, DSORG=PO or DSORG=PS may be 
coded. If the DSORG subparameter is not coded, dsorg=ps is assumed. 

• If the SYSPRINT DD statement is omitted, no messages are written. 

• For an indexed sequential data set, the key length must be specified in the 

DCB. 



PARM Information on the EXEC Statement 



The EXEC statement can include an optional PARM parameter to specify the 
number of lines to be printed between headings in the message data set, coded as 
follows: 

PARM=LINECT=nnnn 

The nnnn is a four-digit decimal number that specifies the number of lines (0000 
to 9999) to be printed per page of output listing. 

If PARM is omitted, 58 lines are printed between headings (unless a channel 12 
punch is encountered in the carriage control tape, in which case a skip to channel 
1 is performed and a heading is printed). 

Note: If IEBDG is invoked, the line-count option can be passed in a parameter 
list that is referred to by a subparameter of the LINK or ATTACH macro 
instruction. In addition, a page count can be passed in a six-byte parameter list 
that is referred to by a subparameter of the LINK or ATTACH macro instruction. 
For a discussion of linkage conventions, refer to "Appendix B: Invoking Utility 
Programs from a Problem Program." 
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Utility Control Statements 

IEBDG is controlled by the following utility control statements: 

• DSD statement, which specifies the ddnames of the input and output data sets. 
One DSD statement must be included for each set of utility control statements. 

• FD statement, which defines the contents and lengths of fields to be used in 
creating output records. 

• CREATE statement, which defines the contents of output records. 

• REPEAT statement, which specifies the number of times a CREATE statement 
or a group of CREATE statements are to be used in generating output records. 

• END statement, which marks the end of a set of IEBDG utility control 
statements. 

Any number of sets of control statements can appear in a single job step. Each 
set defines one data set. 



DSD Statement 



FD Statement 



The DSD statement marks the beginning of a set of utility control statements and 
specifies the data sets that IEBDG is to use as input. The DSD statement can be 
used to specify one output data set and any number of input data sets for each 
application of IEBDG. 

The format of the DSD statement is: 



[label] DSD 



OUTPUT=(ddname) 
[,INPUT=(ddname,...)] 



where: 



OUTPUT= (ddname) 

specifies the ddname of the DD statement defining the output data set. 

INPUT=(ddname,...) 

specifies the ddname of a DD statement defining a data set used as input to 
the program. Any number of data sets can be included as input — that is, any 
number of ddnames referring to corresponding DD statements can be coded. 
Whenever ddnames are included on a continuation card, they must begin in 
column four. 

Note: The ddname SYSIN must not be coded in the INPUT parameter. Each 
parameter should appear no more than once on any DSD statement. 



The FD statement defines the contents and length of a field that will be used 
subsequently by a CREATE statement (or statements) to form output records. A 
defined field within the input logical record may be selected for use in the output 
records if it is referred to, by name, by a subsequent CREATE statement. 

Figure 7-2 shows how fields defined in FD statements are placed in buffer areas 
so that subsequent CREATE statements can assign selected fields to specific 
output records. 
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FD Statements— define fields 




Contents are placed in buffers 
so that subsequent CREATE 
statements can selectively 
create output records. 
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Figure 7-2. Defining and Selecting Fields for Output Records Using iebdg 

Figure 7-3 shows how the FD statement is used to specify a field in an input 
record to be used in output records. The left-hand side of the figure shows that a 
field in the input record beginning at byte 50 is selected for use in the output 
record. The right-hand side of the figure shows that the field is to be placed at 
byte 20 in the output record. 
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Figure 7-3. Field Selected from the Input Record for Use in the Output Record 

The format of the FD statement is: 

[label] FD NAME = name 

,LENGTH=/ength-»n-bytes 
[,STARTLOC=start/ng-byte-/ocat/on] 

[,FILL= {'character 9 } 

{X'2-hexadecimal-digits' }] 

{[,FORMAT=pattern[,CHARACTER=c/iaracter]] 

[,PICTURE=/ength, { 'character -string'} 
{ P'decimal-number 1 } 
{B'decimal- number'}]} 

[,SIGN =s/gn] 

[,ACTION=act/on] 

[,INDEX=number[,CYCLE=number][,RANGE=number]] 

[,INPUT=ddname] 

[,FROMLOC=number] 



IEBDG Program 7-7 



where: 

NAME = name 

specifies the name of the field defined by this FD statement. 

LENGTH= length-in-bytes 

specifies the length in bytes of the defined field. For variable records, four 
bytes of length descriptor are added. 

STARTLOC =starting-byte-location 

specifies a starting location (within all output records using this field) in which 
a field is to begin. For example, if the first byte of an output record is chosen 
as the starting location, the keyword is coded STARTLOC=l; if the tenth byte 
is chosen, STARTLOC=10 is coded, etc. If STARTLOC is omitted, the field will 
begin in the first available byte of the output record (determined by the order 
of specified field names in the applicable CREATE statement). For variable 
records the starting location is the first byte after the length descriptor. 

FILL= 

specifies an EBCDIC character or hexadecimal digits to be placed in each byte 
of the defined field prior to any other operation in the construction of a field. 
If FILL is omitted, binary zeros are placed in the field. These values can be 
coded: 

'character* 

specifies an EBCDIC character to be placed in the defined field. 

X i 2-hexadecimal-digits' > 

specifies two hexadecimal digits (for example, FILL=X'40' or FILL=X'FF') to 
be placed in each byte of the defined field. 

FORMAT= 

specifies an IBM-supplied pattern that is to be placed in the defined field. 
FORMAT must not be used when PICTURE is used. The values that can be 
coded are: 

pattern 

specifies the IBM-supplied patterns, as follows: 

AN 

specifies an alphameric pattern. 

ZD 

specifies a zoned decimal pattern. 

PD 

specifies a packed decimal pattern. 

CO 

specifies a collating sequence pattern. 

BI 

specifies a binary pattern. 

AL 

specifies an alphabetic pattern. 

RA 

specifies a random binary pattern. 

CHARACTER=character 

specifies the starting character of a field. If CHARACTER is omitted, the 
starting character is as described under "IBM-Supplied Patterns" earlier. 
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PICTURE= 

specifies the length and contents of a user-supplied field picture. PICTURE must 
not be used when FORMAT is used. These values can be coded: 

length 

specifies the number of characters in the FD picture. 

'character -string' 

specifies an EBCDIC character string that is to be placed in the defined 
field. The character string is left aligned in the field. A character string may 
be broken in column 71 and must be continued in column 4. Double 
quotation marks must not be coded to represent a single quotation mark: 
within a character string. 

P'dec/ma/- number' 

specifies a decimal number that is to be converted to packed decimal and 
right aligned in the defined field. 

B'dec/ma/- number' 

specifies a decimal number that is to be converted to binary and right 
aligned in the defined field. In all cases, the number of characters within 
the quotation marks must equal the number specified in the LENGTH 
subparameter. 

SIGN=s/gn 

specifies a mathematical sign (+ or -), which is used when defining a packed 
decimal or binary field. If SIGN is omitted, the sign is assumed to be positive. 

ACTION=acf/on 

specifies that the contents of a defined field are to be altered after the field's 
inclusion in an output record. These values can be coded: 

SL 

specifies that the contents of a defined field are to be shifted left after the 
field's inclusion in an output record. 

SR 

specifies that the contents of a defined field are to be shifted right after the 
field's inclusion in an output record. 

TL 

specifies that the contents of a defined field are to be truncated left after 
the field's inclusion in an output record. 

TR 

specifies that the contents of a defined field are to be truncated right after 
the field's inclusion in an output record. 

RO 

specifies that the contents of a defined field are to be rolled after the field's 
inclusion in an output record. RO can be used only for a user-defined field. 

WV 

specifies that the contents of a defined field are to be waved after the 
field's inclusion in an output record. WV can be used only for a user-defined 
field. 

FX 

specifies that the contents of a (defined field are to be fixed after the field's 
inclusion in an output record. If ACTION is omitted, FX is assumed. 

RP 

specifies that the contents of a defined field are to be rippled after the 
field's inclusion in an output record. 
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INDEX= number 

specifies a number to be added to this field whenever a specified number of 
records have been written. If INDEX is omitted, no indexing is performed. 
These additional values can be coded: 

CYCLE=number 

specifies a number of output records (to be written as output or made 
available to an exit routine) that are treated as a group by the INDEX 
keyword. Whenever this field has been used in the construction of the 
specified number of records, it is modified as specified in the INDEX 
parameter. For example, if CYCLE=3 is coded, output records might appear 
as 1 1 1 222 333 444 etc. This parameter can be coded only when INDEX is 
coded. If CYCLE is omitted and INDEX is coded, a CYCLE value of 1 is 
assumed; that is, the field is indexed after each inclusion in a potential 
output record. 

RANGE=number 

specifies an absolute value which the contents of this field can never 
excee^. If an index operation attempts to exceed the specified absolute 
value, the contents of the field as of the previous index operation are used. 

INPUT =ddname 

specifies the ddname for the input data set. 

FROMLOC= number 

specifies the location of the selected field within the input logical record. The 
number represents the position in the input record. If, for example, 
FROMLOC=10 is coded, the specified field begins at the end of the tenth byte; 
if FROMLOC=l is coded, the specified field begins at the end of the first byte. 
(For variable records, significant data begins on the first byte after the 
four-byte length descriptor.) 

Some of the FD keywords do not apply when certain patterns or pictures are 
selected by the user; for example, the index, cycle, range, and SIGN 
parameters are used only with numeric fields. Figure 7-4 shows which IEBDG 
keywords can be used with the applicable pattern or picture chosen by the user. 
Each keyword should appear no more than once on any FD statement. 
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FORMAT/PICTURE 



Compatible Operations 
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*Zoned decimal numbers (ZD) do not include a sign. 

Figure 7-4. Compatible iebdg Operations 



The CREATE statement defines the contents of a record (or records) to be made 
available to a user routine or to be written directly as an output record (or 
records). 

The format of the CREATE statement is: 



[label] CREATE [QUANTITY = number] 

[,FILL= {'character 1 } 

{X* 2 -hexadecimal '-digits*}] 



[,INPUT= {ddname 

{SYSIN[(cccc)] 
[,PICTURE=/ength,starr/oc 



} 

}] 

{,' character -string'} 

{ ,P'dec/mal -number' } 

{ ^decimal -number' } ] 



[,NAME= {name} 

{(namel,namen...)} 
{(name(COPY=namel,namen.. .)...)}] 

[,EXIT = routinename] 
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where: 

QUANTITY == number 

specifies the number of records that this CREATE statement is to generate; 
each record is specified by the other parameters. If QUANTITY is omitted and 
INPUT is not specified, only one output record is created. If QUANTITY is 
omitted and input is specified, the number of records created is equal to the 
number of records in the input data set. If both QUANTITY and INPUT are 
coded, and the quantity specified is greater than the number of records in the 
input data set, the number of records created is equal to the number of input 
records to be processed plus the generated data up to the specified number. 

FILL= 

specifies a value that is to be placed in each byte of the output record before 
any other operation in the construction of record. If FILL is not coded, binary 
zeros are placed in the output record. These values can be coded: 

'character' 

specifies an EBCDIC character that is to be placed in each byte of the 
output record. 

X'2-hexac/ec/ma/-c/»g/fs' 

specifies two hexadecimal digits (for example, FILL=X'40\ or FILL=X'FF') to 
be placed in each byte of the output record. 

INPUT= 

defines an input data set whose records are to be used in the construction of 
output records. If INPUT is not coded, the output records are created entirely 
from utility control statements. If INPUT is coded, QUANTITY should also be 
coded, unless the remainder of the input records are all to be processed by 
this CREATE statement. These values can be coded: 

ddname 

specifies the ddname of a DD statement defining an input data set. 

SYSIN[(cccc)] 

specifies that the SYSIN data set (input stream) contains records (other than 
utility control statements) to be used in the construction of output records. 
If SYSIN is coded, the input records follow this CREATE statement (unless 
the CREATE statement is in a REPEAT group, in which case the input 
records follow the last CREATE statement of the group). When 
INPUT=SYSIN with no cccc value is coded, the input records are delimited 
from any additional utility control statements by a record containing $$$# in 
columns 1 through 4. If this value is coded, the input records are delimited 
by a record containing EBCDIC characters beginning in column 1 ; the cccc 
can be any combination of from one to four EBCDIC characters. 

PICTURE= 

specifies the length, starting byte, and contents of a user-supplied picture 
(CREATE statement picture). If both PICTURE and NAME are omitted, the fill 
character specified in the CREATE statement appears in each byte of 
applicable output records. These values can be coded: 

length 

specifies the number of bytes that the picture will occupy. 

startloc 

specifies a starting byte (within any applicable output record) in which the 
picture is to begin. 
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'character -string' 

specifies an EBCDIC character string that is to be placed in the applicable 
record(s). The character string is left aligned at the defined starting byte. A 
character string may be broken in column 71 and continued in column 4. 

^decimal-number' 

specifies a decimal number that is to be converted to packed decimal and 
right aligned (within the boundaries of the defined length and starting byte) 
in the output records. 

B'decimal- number' 

specifies a decimal number that is to be converted to binary and right 
aligned (within the boundaries of the defined length and starting byte) in 
the output records. 

NAME= 

specifies the name or names of previously defined fields to be included in the 
applicable output records. If both NAME and PICTURE are omitted, the fill 
character specified in the CREATE statement appears in each byte of the 
applicable output record. These values can be coded: 

{namely..) 

specifies the name or names of a field or fields to be included in the 
applicable output record(s). Each field is included in an output record in 
the order in which its name is encountered in the CREATE statement. 

COPY=number 

indicates that all fields named in the inner parentheses (maximum of 
twenty) are to be treated as a group and included the specified number of 
times in each output record produced by this CREATE statement. Any 
number of sets of inner parentheses can be included with NAME; however, 
sets of parentheses cannot be embedded. Within each set of inner 
parentheses, COPY must appear before the name of any field. 

EXIT = routinename 

specifies the name of a user routine that is to receive control from IEBDG 
before writing each output record. 

After processing each potential output record, the user routine provides a return 
code to instruct IEBDG how to handle the output record. The user codes are: 

• 00, which specifies that the record is to be written. 

• 04, which specifies that the record is not to be written. The skipped record is 
not to be counted as a generated output record; processing is to continue as 
though a record were written. If skips are requested through user exits and 
input records are supplied, each skip causes an additional input record to be 
processed in the generation of output records. For example, if a CREATE 
statement specifies that ten output records are to be generated and a user exit 
indicates that two records are to be skipped, 12 input records are processed. 

• 12, which specifies that the processing of the remainder of this set of utility 
control statements is to be bypassed. Processing is to continue with the next 
DSD statement. 

• 16, which specifies that all processing is to halt. 

Note: When an exit routine is loaded and when the user returns control to 
IEBDG, register one contains the address of the first byte of the output record. 
Each keyword should appear no more than once on any CREATE statement. 

Figure 7-5 shows the addition of field X to two different records. In record 1 , 
field X is the first field referred to by the CREATE statement; therefore, field X 
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begins in the first byte of the output record. In record 2, two fields, field A and 
field B, have already been referred to by a CREATE statement; field X, the next 
field referred to, begins immediately after field B. Field X does not have a special 
starting location in this example. 
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80 



Record 2 
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80 
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Figure 7-5. Default Placement of Fields Within an Output Record Using iebdg 

The user can also indicate that a numerical field is to be modified after it has 
been referred to n times by a CREATE statement or statements, that is, after n 
cycles, a modification is to be made. A modification will add a user-specified 
number to a field. 

The CREATE statement constructs an output record by referring to previously 
defined fields by name and/or by providing a picture to be placed in the record. 
The user can generate multiple records with a single CREATE statement. 

When defining a picture in a CREATE statement, the user must specify its length 
and starting location in the output record. The specified length must be equal to 
the number of specified EBCDIC or numeric characters. (When a specified 
decimal number is converted to packed decimal or binary, it is automatically right 
aligned.) 

Figure 7-6 shows three ways in which output records can be created from utility 
control statements. 
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Figure 7-6. Creating Output Records with Utility Control Statements 



7-14 OS/VS Utilities 



REPEAT Statement 



As an alternative to creating output records from utility control statements alone, 
the user can provide input records, which can be modified and written as output 
records. Input records can be provided directly in the input stream, or in a data 
set. 

As previously mentioned, the CREATE statement is responsible for the 
construction of an output record. An output record is constructed in the 
following order: 

1. A fill character, specified or default (binary zero), is initially loaded into each 
byte of the output record. 

2. An input record, if any is provided, is left aligned in the output record. 

3. FD fields, if any, are placed in the output record in the order of the 
appearance of their names in the CREATE statement. 

4. A CREATE statement picture, if any, is placed in the output record. 

IEBDG provides a user exit so that the user can provide his own routine to 
analyze or further modify a newly constructed record before it is placed in the 
output data set. 

A set of utility control statements contains one DSD statement, any number of 
FD, CREATE, and REPEAT statements, and one END statement when the INPUT 
parameter is omitted from the FD card. 

When selecting fields from an input record (FD INPUT=ddname), the field must be 
defined by an FD statement within each set of utility control statements. In this 
case, defined fields for field selection are not usable across sets of utility control 
statements. The FD card may be duplicated and used in more than one set of 
utility control statements within the job step. 



The REPEAT statement specifies the number of times a CREATE statement or 
group of CREATE statements is to be used repetitively in the generation of output 
records. The REPEAT statement precedes the CREATE statements to which it 
applies. 

Figure 7-7 shows a group of five CREATE statements repeated n times. 




CREATE (1) 
CREATE (2) 
CREATE (3) 
CREATE (4) 
CREATE (5) 

CREATE (1) 
CREATE (2) 
CREATE (3) 
CREATE (4) 
CREATE (5) 



CREATE (1) 
CREATE (2) 
CREATE (3) 
CREATE (4) 
CREATE (5) 



Figure 7-7. Repetition Due to the REPEAT Statement Using IEBDG 
The format of the REPEAT statement is: 

[label] REPEAT QUANTITY=number[,CREATE=number] 
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END Statement 



IEBDG Examples 



IEBDG Example 1 



where: 

QUANTITY=number 

specifies the number of times the defined group of CREATE statements is to be 
used repetitively. This number cannot exceed 65,535. 

CREATE=number 

specifies the number of following CREATE statements to be included in the 
group. If the CREATE parameter is omitted, only one CREATE statement is 
repeated. 



The END statement is used to mark the end of a set of utility control statements. 
Each set of control statements can pertain to any number of input data sets and 
a single output data set. 

The format of the END statement is: 

[label] END 



The following examples illustrate some of the uses of IEBDG. Table 7-3 can be 
used as a quick reference guide to IEBDG examples. The numbers in the 
"Example" column point to examples that follow. 



Table 7-3. IEBDG 


Example Directory 








Data Set 








Operation 


Organization 


Device 


Comments 


Example 


Place binary zeros in 


Sequential 


9-track Tape 


: Blocked input and 




selected fields. 






output. 


1 


Ripple alphabetic 


Sequential 


9-track Tape, Blocked input and 




pattern 




2314 Disk 


output. 


2 


Create output records 


Sequential 


2314 Disk 


Blocked output. 


3 


from utility control 










statements 










Modify records from 


Partitioned, 


2314 Disk 


Reblocking is performed. 




partitioned members 


Sequential 




Each block of output 




and input stream 






records contains ten 
modified partitioned 
input records and two 
input stream records. 


4 


Create partitioned 


Partitioned 


2314 Disk 


Blocked output. One set 




members for utility 






of utility control 




control statements 






statements per member. 


5 


Roll and wave user- 


Sequential 


2314 Disk 


Output records are 




supplied patterns 






created from utility 
control statements. 


6 


Create indexed 


Sequential, 


2314 Disk 


Output records are 




sequential data set 


Indexed 




created by augmenting 




using field selection 


sequential 




selected input fields 




and data generation 






with generated data. 


7 



In this example, binary zeros are to be placed in two fields of records copied 
from a sequential data set. After the operation, each record in the copied data set 
(OUTSET) contains binary zeros in locations 20 through 29 and 50 through 59. 
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The example follows: 

72 

//CLEAROUT JOB , , MSGLEVEL= 1 

// EXEC PGM=IEBDG 

//SYSPRINT DD SYSOUT=A 

//SEQIN DD DSNAME=INSET,UNIT=2400,DISP=( OLD, KEEP), 

// DCB=(RECFM=FB,LRECL=80,BLKSIZE=800),LABEL=( , NL ) , 

// VOLUME=SER=240000 

//SEQOUT DD DSNAME=OUTSET,UNIT=2400,VOLUME=SER=240001 , 

// DCB=(RECFM=FB,LRECL=80,BLKSIZE=800 ),DISP=( ,KEEP), 

// LABEL=( ,NL) 

//SYSIN DD * 

DSD OUTPUT=( SEQOUT ) , INPUT=( SEQIN ) 

FD NAME=FIELD 1 , INPUT=SEQIN , LENGTH=80 

FD NAME=FIELD2 , LENGTH^ 1 , STARTLOC=20 

FD NAME=FIELD3 , LENGTH= 1 , STARTLOC=50 

CREATE QUANTITY=100,INPUT=SEQIN,NAME=(FIELD1 ,FIELD2, C 

FIELD3 ) 
END 



/* 



IEBDG Example 2 



The control statements are discussed below: 

• SEQIN DD defines a sequential input data set (INSET). The data set was 
originally written on a 9-track, unlabeled tape volume. 

• SEQOUT DD defines the test data set (OUTSET). The output records are 
identical to the input records, except for locations 20 through 29 and 50 
through 59, which contain binary zeros at the completion of the operation. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• DSD marks the beginning of a set of utility control statements and refers to 
the DD statements defining the input and output data sets. 

• The first FD statement defines an 80-byte field of input data. 

• The second and third FD statements create two ten-byte fields (FIELD2 and 
FIELD3) that contain binary zeros. The fields are to begin in the 20th and 50th 
bytes of each output record. 

• CREATE constructs 100 output rcords in which the contents of previously 
defined fields (FIELD l, FIELD2, FIELD3) are placed in their respective starting 
locations in each of the output records. Input records from data set INSET are 
used as the basis of the output records. 

• END signals the end of a set of utility control statements. 



In this example, a ten-byte alphabetic pattern is to be rippled. At the end of the 
job step the first output record contains "ABCDEFGHIJ", followed by data in 
location 1 1 through 80 from the input record; the second record contains 
"BCDEFGHIJK" followed by data in locations 1 1 through 80, etc. 
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The example follows: 



72 



//RIPPLE JOB ,,MSGLEVEL=1 

// EXEC PGM=IEBDG 

//SYSPRINT DD SYSOUT=A 

//SEQIN DD DSNAME=INSET,DISP=( OLD, KEEP ),VOL=SER=240000, 

// DCB=( RECFM=FB , LRECL=80 , BLKSIZE=800 ) , UNIT=2400 

//SEQOUT DD DSNAME=OUTSET,UNIT=2314,VOLUME=SER=231400, 

// DCB=(RECFM=FB,LRECL=80,BLKSIZE=800),DISP=( ,KEEP), 

// SPACE=( TRK, (10,10)) 

//SYSIN DD * 

DSD OUTPUT=( SEQOUT ) , INPUT=( SEQIN ) 
FD NAME=FIELD1 , INPUT=SEQIN, LENGTH=80 
FD NAME=FIELD2 , LENGTH= 1 , FORMAT=AL , ACTION=RP , 
STARTLOC=1 
QUANTITY=1 00, INPUT=SEQIN,NAME=( FIELD 1 ,FIELD2 ) 



/* 



IEBDG Example 3 



CREATE 
END 



The control statements are discussed below: 

• SEQIN DD defines an input sequential data set (INSET). The data set was 
originally written on a 9-track, standard labeled tape volume. 

• SEQOUT DD defines the test output data set (OUTSET). Twenty tracks of 
primary space and ten tracks of secondary space are allocated for the 
sequential data set on a 2314 volume. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• DSD marks the beginning of a set of utility control statements and refers to 
the DD statements defining the input and output data sets. 

• The first FD statement defines an 80-byte field of input data. 

• The second FD statement creates a ten-byte field in which the pattern 
ABCDEFGHIJ is placed. The data is rippled after each output record is written. 

• CREATE constructs 100 output records in which the contents of a previously 
defined field (FIELD l) are included. The CREATE statement uses input records 
from data set INSET as the basis of the output records. 

• END signals the end of a set of utility control statements. 



In this example, output records are to be created entirely from utility control 
statements. Three fields are to be created and used in the construction of the 
output records. In two of the fields, alphabetic data is to be truncated; the other 
field is a numeric field that is to be incremented (indexed) by one after each 
output record is written. Figure 7-8 shows the contents of the output records at 
the end of the job step. 



Field 1 
1 


Field 2 
31 


Field 3 (packed dec 
61 71 


mal) 
80 


ABCDEFGHIJKLMNOPQRSTUVWXYZABCD 


ABCDEFGHIJKLMNOPQRSTUVWXYZABCD 


FF . 


. FF 


123 . . 


.90 


BCDEFGHIJKLMNOPQRSTUVWXYZABCD 


ABCDEFGHIJKLMNOPQRSTUVWXYZABC 


FF . 


. FF 


123 . . 


.91 


CDEFGHIJKLMNOPQRSTUVWXYZABCD 


ABCDEFGHIJKLMNOPQRSTUVWXYZAB 


FF . 


. FF 


123 . . 


.92 


DEFGHIJKLMNOPQRSTUVWXYZABCD 


ABCDEFGHIJKLMNOPQRSTUVWXYZA 


FF . 


. FF 


123. . 


.93 


EFGHIJKLMNOPQRSTUVWXYZABCD 


ABCDEFGHIJKLMNOPQRSTUVWXYZ 


FF . 


. FF 


123. . 


.94 



Figure 7-8,, Output Records at Job Step Completion 
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The example follows: 
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//UTLYONLY JOB , ,MSGLEVEL=1 

// EXEC PGM=IEBDG 

//SYSPRINT DD SYSOUT=A 

//SEQOUT DD DSNAME=OUTSET,UNIT=2314,DISP=( ,KEEP), 

// DCB=(RECFM=FB,LRECL=80,BLKSIZE=800),SPACE=(TRK,( 10,10)), 

// VOLUME=SER=240000 

//SYS IN DD DATA 
DSD OUTPUT=( SEQOUT ) 

FD NAME=FIELD1 , LENGTH=30 , STARTLOC=1 , FORMAT=AL, ACTION=TL 
FD NAME=FIELD2,LENGTH=30,STARTLOC=31 , FORMAT=AL, ACTION=TR 
FD NAME=FIELD3,LENGTH=10,STARTLOC=71 ,PICTURE=10, C 

P' 1234567890' ,INDEX=1 
CREATE QUANTITY= 1 00, NAME=( FIELD 1 , FIELD2 , FIELD3 ),FILL=X'FF' 
END 

/* 

The control statements are discussed below: 

• SEQOUT DD defines the test output data set. Ten tracks of primary space and 
ten tracks of secondary space are allocated for the sequential data set on a 
2314 volume. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• DSD marks the beginning of a set of utility control statements and refers to 
the DD statement defining the output data set. 

• FD defines the contents of three fields to be used in the construction of output 
records. The first field contains 30 bytes of alphabetic data to be truncated 
left after each output record is written. The second field contains 30 bytes of 
alphabetic data to be truncated right after each output record is written. The 
third field is a ten-byte field containing a packed decimal number 
(1234567890) to be incremented by one after each record is written. 

• CREATE constructs 100 output records in which the contents of previously 
defined fields (FIELD 1, FIELD2, and FIELD3) are included. 

• END signals the end of a set of utility control statements. 



In this example, two partitioned members and input records from the input 
stream are to be used as the basis of a partitioned output member. Each block: of 
12 output records is to contain ten modified records from an input partitioned 
member and two records from the input stream. Figure 7-9 shows the content of 
the output partitioned member at the end of the job step. 
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Input 
Department 21 



(Rightmost 67 bytes of INSET 1 (MEMBA) record !) 



Department 21 (Rightmost 67 bytes of INSET1 (MEMBA) record 10) 

Input record 1 from input stream 

Input record 2 from input stream 

Department 21 (Rightmost 67 bytes of INSET1 (MEMBA) record 11) 



Department 21 (Rightmost 67 bytes of INSET1 (MEMBA) record 20) 

Input record 3 from input stream 11 

Input record 4 from input stream 12 



Department 21 



(Rightmost 67 bytes of INSET1 (MEMBA) record 91) 



Department 21 (Rightmost 67 bytes of INSET1 (MEMBA) record 100) 

Input record 19 from input stream 11 

Input record 20 from input stream 12 



Department 21 



(Rightmost 67 bytes of INSET2 (MEMBA) record 1) 



Department 21 (Rightmost 67 bytes of INSET2 (MEMBA) record 10) 

Input record 21 from input stream 11 

Input record 22 from input stream 12 



Output Records 
1 1st block of 12 



10 
11 
12 

1 2nd block of 12 



1 10th block of 12 

10 
12 

1 11th block of 12 



Figure 7-9. Output Partitioned Member at Job Step Completion 

The example follows: 

//MIX JOB , ,MSGLEVEL=1 

// EXEC PGM=IEBDG 

//SYSPRINT DD SYSOUT=A 

//PARIN1 DD DSNAME-INSET1(MEMBA),UNIT=2314,DISP=OLD, 

// DCB=( RECFM=FB , LRECL=80 , BLKSIZE=800 , DSORG=PS ) , 

// VOLUME=SER=231400 

//PARIN2 DD DSNAME-INSET2(MEMBA),UNIT=2314,DISP=OLD, 

// DCB=( RECFM=FB , LRECL-80 , BLKSIZE=960 , DSORG=PS ) , 

// VOLUME=SER=2 31401 

//PAROUT DD DSNAME-PARSET( MEMBA ),UNIT=231 4, DISP=( , KEEP), 

// VOLUME=SER=231402,SPACE=(TRK,( 10,10,5) ) , DCB=( RECFM=FB, 

// LRECL=80 , BLKSIZE=960 , DSORG=PS ) 

//SYSIN DD DATA 

DSD OUTPUT=( PAROUT ) , INPUT=( PARIN1 ,PARIN2 ) 

FD NAME=FIELD 1 , LENGTH= 1 3 , PICTURE= 13,' DEPARTMENT 2 1 ' 

REPEAT QUANTITY=10,CREATE=2 

CREATE QUANTITY=10,INPUT=PARIN1 ,.NAME=FIELD1 

CREATE QUANTITY=2,INPUT=SYSIN 

(input records 1 through 20) 

$$$E 

REPEAT QUANTITY=10,CREATE=2 

CREATE QUANTITY= 1 , INPUT=PARIN2 , NAME=FIELD 1 

CREATE QUANTITY=2,INPUT=SYSIN 

(input records 21 through 40) 

$$$E 

END 
/* 

The control statements are discussed below: 

• PARIN1 DD defines one of the input partitioned members. 

• PARIN 2 dd defines the second of the input partitioned members. (Note that 
the members are from different partitioned data sets.) 
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PAROUT DD defines the output partitioned member. This example assumes 
that the partitioned data set does not exist prior to the job step; that is, this 
DD statement allocates space for the partitioned data set. 

SYSIN DD defines the control data set, which follows in the input stream. 

DSD marks the beginning of a set of utility control statements and refers to 
the DD statements defining the input and output data sets. 

FD creates a 13-byte field in which the picture "department 21" is placed. 

The first REPEAT statement indicates that the following group of two CREATE 
statements is to be repeated ten times. 

The first CREATE statement creates ten output records. Each output record is 
constructed from an input record (from partitioned data set INSET l) and from 
previously defined FIELD l. 

The second CREATE statement indicates that two records are to be 
constructed from input records included next in the input stream. 

The $$$E record separates the input records from the REPEAT statement. The 
next REPEAT statement group is identical to the preceding group, except that 
records from a different partitioned member are used as input. 

END signals the end of a set of utility control statements. 



In this example, output records are to be created from three sets of utility control 
statements and written in three partitioned data set members. Four fields are to 
be created and used in the construction of the output records. In two of the 
fields (FIELD l and FIELD3), alphabetic data is to be shifted. The other two fields 
are to be fixed alphameric and zoned decimal fields. Figure 7-10 shows the 
partitioned data set members at the end of the job step. 
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Figure 7-10. Partitioned Data Set Members at Job Step Completion 
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The example follows: 

//UTSTS JOB ,,MSGLEVEL=1 

// EXEC PGM= IEBDG 

//SYSPRINT DD SYSOUT^A 

//PAROUT1 DD DSNAME=PARSET(MEMBA),UNIT=2314,DISP=( ,KEEP), 

// VOLUME=SER=231400,SPACE=(TRK,( 10,10,5) ) , DCB=( RECFM=FB, 

// LRECL=80 , BLKSIZE=800 , DSORG=PS ) 

//PAROUT2 DD DSNAME=PARSET( MEMBB ) , UNIT=AFF=PAROUT1 , 

// DCB=( RECFM=FB , LRECL=80 , BLKSIZE=800 , DSORG=PS ) , DISP=OLD , 

// VOLUME=SER=231400 

//PAROUT3 DD DSNAME=PARSET( MEMBC ) , UNIT=AFF=PAROUT1 , 

// DCB=( RECFM=FB , LRECL-80 , BLKSIZE=800 , DSORG=PS ) , DISP=OLD, 

// VOLUME=SER=231400 

//SYSIN DD DATA 

OUTPUT=(PAROUT1 ) 

NAME=FIELD 1 , LENGTH=30 , FORMAT=AL , ACTION=SL 

NAME=FIELD2 , LENGTH=20 , FORMAT=ZD 

NAME=FIELD3,.LENGTH=20,FORMAT=AL,ACTION=SR 

NAME=FIELD4 , LENGTH=30 , FORMAT=AN 

QUANTITY=4,NAME=( FIELD 1 , FIELD3 , FIELD2 ) 



DSD 

FD 

FD 

FD 

FD 

CREATE 

END 

DSD 

CREATE 

END 

DSD 

CREATE 

END 



OUTPUT- (PAROUT2 ) 

QUANTITY=4,NAME=( ( COPY=3 , FIELD 3 ),FIELD2 

OUTPUT=( PAROUT3 ) 
QUANTITY=4,NAME=( FIELD4, FIELD 1 ) 



/> 



The control statements are discussed below: 

• PAROUTl DD defines the first member (MEMBA) of the partitioned output data 
set. This example assumes that the partitioned data set does not exist prior to 
this job step; that is, this DD statement allocates space for the data set. 

• PAROUT2 and PAROUT3 DD define the second and third members, 
respectively, of the output partitioned data set. Note that each DD statement 
specifies DISP=OLD and UNIT=AFF=PAROUTl. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• DSD marks the beginning of a set of utility control statements and refers to 
the DD statement defining the member applicable to that set of utility control 
statements. 

• FD defines the contents of a field that is used in the subsequent construction 
of output records. 

• CREATE constructs four records from combinations of previously defined 
fields. 

• END signals the end of a set of utility control statements. 



In this example, ten fields containing user-supplied EBCDIC pictures are to be 
used in the construction of output records. After a record is written, each field is 
rolled or waved, as specified in the applicable FD statement. Figure 7-11 shows 
the contents of the output records at the end of the job step. 
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Figure 7-11. Contents of Output Records at Job Step Completion 

The example follows: 



//ROLLWAVE JOB , , MSGLEVEL= 1 

// EXEC PGM=IEBDG 

//SYSPRINT DD SYSOUT=A 

//OUTSET DD DSNAME=SEQSET,UNIT=2314,DISP=( , KEEP ) , 

// VOLUME=SER=SAMP , SPACE= ( TRK ,(10,10)), DCB= ( RECFM=FB , 

// LRECL=80,BLKSIZE=800) 

//SYSIN DD * 
DSD OUTPUT=( OUTSET) 

FD NAME=FIELD1 , LENGTH=8 , PICTURED , ' AAAAA' ,ACTION=RO 
FD NAME=FIELD2 , LENGTH=8 , PICTURE=8 , ' BBBBB ' , ACTION=RO 
FD NAME=FIELD3,LENGTH=8,PICTURE=8, 'A AA ',ACTION=RO 
FD NAME=FIELD4,LENGTH=8,PICTURE=8, ' BB B',ACTION=RO 
FD NAME=FIELD5,LENGTH=8,PICTURE=8, ' AAA ',ACTION=RO 
FD NAME=FIELD6 , LENGTH=8 , PICTURE=8 , ' CCCCC ' , ACTION=WV 
FD NAME=FIELD7,LENGTH=8,PICTURE=8, ' DDDD ',ACTION=WV 
FD NAME=FIELD8,LENGTH=8,PICTURE=8, ' C CC ' ,ACTION=WV 
FD NAME=FIELD9,LENGTH=8,PICTURE=8, ' DD D',ACTION=WV 
FD NAME=FIELD10,LENGTH=8,PICTURE=8, ' CCC ' ,ACTION=WV 
CREATE QUANTITY=300,NAME=(FIELD1 , FIELD2 , FIELD3 , C 

FIELD4 , FIELD5 , FIELD6 , FIELD7 , FIELD8 , C 

FIELD9,FIELD10 ) 
END 

/* 

The control statements are discussed below: 

• OUTSET DD defines the output sequential data set on a 2314 volume. Twenty 
tracks of primary space and ten tracks of secondary space are allocated to the 
data set. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• DSD marks the beginning of a set of utility control statements and refers to 
the DD statement defining the output data set. 

• FD defines a field to be used in the subsequent construction of output records. 
Note that the direction and frequency of the initial roll or wave depends on 
the location of data in the field. 

• CREATE constructs 300 records from the contents of the previously defined 
fields. 

• END signals the end of a set of utility control statements. 



IEBDG Program 7-23 



IEBDG Example 7 



In this example, the first -ten bytes of the output record contain data generated in 
zoned decimal format. This field serves as the key field for the output record in 
the output indexed sequential data set. The key field is incremented (indexed) by 
one for each record. The input sequential data set provides an additional 80-byte 
field to complete the output record. 
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The example follows: 

//CREATE IS JOB MSGLEVEL=1 

//BEGIN EXEC PGM=IEBDG 

//TAPEIN DD DCB=(BLKSIZE=80,LRECL=80,RECFM=F), 

// DISP=( OLD, KEEP ) , UNIT=2400 , LABEL=( ,SL), 

// DSNAME=TAPEIT,VOL=SER=MASTER 

//DISKOUT DD DCB=(BLKSIZE=270,LRECL=90,RECFM=FB, 

// DSORG=IS , NTM=2 , OPTCD=MY , RKP=0 , KEYLEN= 1 , 

// CYLOFL=1 ),UNIT=2314,SPACE=(CYL, 1 ) ,DISP=( NEW, KEEP ) , 

// VOL=SER=231400,DSNAME=CREATIS 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD * 

DSD OUTPUT=( DISKOUT ) , INPUT=( TAPEIN ) 

FD NAME=DATAFD , LENGTH= 8 , FROMLOC= 1 , C 

STARTLOC=1 1 , INPUT=TAPEIN 

FD NAME=KEYFD , LENGTH= 1 , STARTLOC= 1 , FORMAT=ZD , INDEX= 1 

CREATE INPUT=TAPEIN , NAME= ( KEYFD , DATAFD ) 

END 
/* 

The control statements are discussed below: 

• TAPEIN DD defines the sequential input data set. 

• DISKOUT DD defines the indexed sequential output data set. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• DSD marks the beginning of a set of utility control statements and refers to 
the DD statement defining the output data set. 

• FD defines a field that will be used in the subsequent construction of output 
records. The first FD statement in this example defines and locates an 80-byte 
field of input data. The data is field selected from one of the input logical 
records and placed at start location 1 1 of the output logical record. The 
second FD statement defines and locates the ten-byte key field. 

• CREATE? constructs a 90-byte output record by referring to the previously 
defined fields. 

• END signals the end of a set of utility control statements. 



7-24 OS/VS Utilities 



IEBEDIT Program 



Input and Output 



IEBEDIT is a data set utility used to create an output data set containing a 
selection of jobs or job steps. (See "Introduction" for general data set utility 
information.) At a later time, the data set can be used as an input stream for job 
processing. 

Note: All references to JES2 control statements apply to VS2 only. 

IEBEDIT creates an output job stream by editing and selectively copying a job 
stream provided as input. The program can copy: 

• An entire job or jobs, including JOB statements and any associated JOBLIB 
statements, and JES2 control statements. 

• Selected job steps, including the JOB statement, JES2 control statements 
following the JOB statement, and any associated joblib statement. 

All selected JOB statements, JES2 control statements, JOBLIB statements, jobs, or 
job steps are placed in the output data set in the same order as they exist in (he 
input data set. Note that a JES2 control statement or a joblib statement is 
copied only if it follows a selected JOB statement. 

When IEBEDIT encounters a selected job step containing an input record having 
the characters "..*" in columns 1 through 3, the program automatically converts 
that record to a termination statement (/*b statement) and places it in the 
output data set. 

Note: A "/*nonblank" indicates a JES2 control statement. 



IEBEDIT uses the following input: 

• An input data set, which is a sequential data set consisting of a job stream. 
The input data set is used as source data in creating an output sequential data 
set. 

• A control data set, which contains utility control statements that are used to 
specify the organization of jobs and job steps in the output data set. 

IEBEDIT produces the following output: 

• An output data set, which is a sequential data set consisting of a resultant job 
stream. 

• A message data set, which is a sequential data set that contains applicable 
control statements, error messages, if applicable, and, optionally, the output 
data set. 

IEBEDIT provides a return code to indicate the results of program execution. The 
return codes and their meanings are: 

• 00, which indicates successful completion. 

• 04, which indicates that an error occurred. The output data set may not be 
usable as a job stream. Processing continues. 

• 08, which indicates that an unrecoverable error occurred while attempting to 
process the input, output, or control data set. The job step is terminated. 
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Control 



IEBEDIT is controlled by job control statements and utility control statements. 
The job control statements are required to execute or invoke the program and to 
define the data sets used and produced by the program. The utility control 
statements are used to control the functions of the program. 



Job Control Statements 



Table 8-1 shows the job control statements necessary for using IEBEDIT. 

Table 8-1. iebedit Job Control Statements 

Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (PGM=IEBEDIT) or, if the job control 

statements reside in a procedure library, the procedure name. 

SYSPRINT DD Defines a sequential message data set. The data set can be written to a 
system output device, a tape volume, or a direct access volume. 

SYSUT1 DD Defines a sequential input data set on a card reader, tape volume, or direct 

access device. 

SYSUT2 DD Defines a sequential output data set on a card punch, printer, tape volume, 

or direct access device. 

SYSIN DD Defines the control data set. The data set normally is included in the input 

stream; however, it can be defined as a member of a procedure library or 
as a sequential data set existing somewhere other than in the input stream. 

Restrictions 

• The block size for the SYSPRINT data set must be a multiple of 121. The 
block size for the SYSIN, SYSUTl, and SYSUT2 data sets must be a multiple of 
80. Any blocking factor can be specified for these block sizes. 

Utility Control Statement 

IEBEDIT is controlled through the EDIT utility control statement. 



EDIT Statement 



The EDIT statement indicates which step or steps or a specified job in the input 
data set are to be included in the output data set. Any number of EDIT 
statements can be included in an operation, thus including selected jobs in the 
output data set. 

EDIT statements must be included in the same order as the input jobs that they 
represent. If no EDIT statement is present in the control data set, the entire input 
data set is copied. 

The format of the EDIT statement is: 

[label] EDIT [ST ART =jobname] 

[,TYPE= { POSITION } 
{INCLUDE} 
{EXCLUDE}] 

[,STEPNAME=({name-name}[,{name-narne}] 

{name } [,{name}],...)] 

[,NOPRINT] 
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where: 

START = jobname 

specifies the name of the input job to which the EDIT statement applies. (Each 
EDIT statement must apply to a separate job.) If START is specified without 
TYPE and STEPNAME, the JOB statement and all job steps for the specified job 
are included in the output. If start is omitted and only one EDIT statement is 
provided, the first job encountered in the input data set is processed. If START 
is omitted from an EDIT statement other than the first statement, processing 
continues with the next JOB statement found in the input data set. 

TYPE= 

specifies the contents of the output data set. If TYPE is omitted, 
type=POSITION is assumed. These values can be coded: 

POSITION 

specifies that the output is to consist of a JOB statement, the job step 
specified in the STEPNAME parameter, and all steps that follow it. All job 
steps preceding the specified step are omitted from the operation. This is 
the default. 

INCLUDE 

specifies that the output data set is to contain a JOB statement and all job 
steps specified in the STEPNAME parameter. 

EXCLUDE 

specifies that the output data set is to contain a JOB statement and all job 
steps belonging to the job except those steps specified in the STEPNAME: 
parameter. 

STEPNAME= 

specifies the first job step to be placed in the output data set when coded with 
TYPE=POSlTiON. Job steps preceding this step are not copied to the output 
data set. When coded with type=include or type=exclude, stepname 
specifies the names of job steps that are to be included in or excluded from 
the operation. For example, stepname=(stepa,stepfstepl,stepz) indicates 
that job steps STEPA, STEPF through STEPL, and STEPZ are to be included in 
or excluded from the operation. If STEPNAME is omitted, the entire input job 
whose name is specified on the EDIT statement is copied. If no job name is 
specified, the first job encountered is processed. 

NOPRINT 

specifies that the message data set is not to include a listing of the output data 
set. If NOPRINT is omitted, the resultant output is listed in the message data 
set. 

Note: 

1. Any JES2 control statement or JOBLIB DD statement that follows a selected 
JOB statement is automatically copied to the output data set. 

2. JES2 control statements preceding the JOB statement are assumed to belong to 
the previous job. 

3. JES2 control statements preceding the first JOB statement are included only if a 
total copy is requested. 

4. JES2 control statements within selected job steps are included. 

5. JES2 control statements within a DD DATA stream are included only if a 
delimiter other than "/*" is coded in the DD DATA card. For a description of 
coding another delimiter see OS/VS Job Control Language Reference, 
GC28-6704. If another delimiter is not coded, the first two characters of the 
JES2 control statement will act as a delimiter to DD DATA. 
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IEBEDIT Examples 



The following examples show some of the uses of IEBEDIT. Table 8-2 can be 
used as a quick reference guide to IEBEDIT examples. The numbers in the 
"Example" column point to examples that follow. 



Table 8-2. iebedit Example Directory 



Operation Devices 
COPY 



COPY 



COPY 



COPY 



COPY 



COPY 



9-track Tape 
7 -track Tape 



2314 Disk, 
9-track Tape 

2314 or 2319 
Disk 1 

9-track Tape 



9-track Tape 



Comments 

The input data set contains three jobs. One job is 
to be copied. 

The output data set is the second data set on the 
volume. One job step is to be copied from each of 
three jobs. 

Include a job step from one job and exclude a 
job step from another job. 

Latter portion of a job stream is to be copied 

All records in the input data set are to be copied. 
The "..*" record is converted to a "/*b" 
statement in the output data set. 

The input contains a JES2 control statement 
and a new delimiter. 



Example 



1 The 23 19 disk is functionally equivalent to the 2314 disk; to use the 2319, specify 2314 in the 
control statement. 
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In this example one job (JOBA), including all of its job steps (A, B, C, and D), is 
to be copied into the output data set. The input data set contains three jobs: 
JOBA, which has four job steps; JOBB, which has three job steps; and JOBC, 
which has two job steps. 

The example follows: 



//EDIT1 

// 

//SYSPRINT DD 
//SYSUT1 DD 
//SYSUT2 DD 



JOB 09 #440, SMITH 
EXEC PGM=IEBEDIT 
SYSOUT=A 

UNIT=2400, DISP=( OLD, KEEP ) , VOLUME=SER=00 1234 
UNIT=2400 , DISP=( NEW, KEEP ) , VOLUME=SER=00 1235, 
// DCB=( RECFM=F , LRECL=80 , BLKSIZE=80 ) , DSNAME=OUTTAPE 
//SYSIN DD * 

EDIT START=JOBA 
/* 

The control statements are discussed below: 

• SYSUTl DD defines the input data set. The data set resides on a 9-track, 
standard labeled tape volume (001234). 

• SYSUT2 DD defines the output data set. The data set is to reside as the first 
data set on a standard labeled, 9-track tape volume (001235), 

• SYSIN DD defines the control data set, which follows in the input stream. 

• EDIT indicates that JOBA is to be copied in its entirety. 



IEBEDIT Example 2 



This example copies: (1) the JOB statement and steps STEPC and STEPD for 
JOBA, (2) the JOB statement and STEPE for JOBB, and (3) the JOB statement and 
STEPJ for JOBC. The input data set contains three jobs: JOBA, which includes 
stepa, stepb, stepc, and stepd; jobb, which includes STEPE, stepf, and 
STEPG; and JOBC, which includes STEPH and STEPJ. 
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IEBEDIT Example 3 



IEBEDIT Example 4 



The example follows: 

//EDIT2 JOB 09#440, SMITH 

// EXEC PGM-IEBEDIT 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DISP=( OLD, KEEP ) , VOLUME=SER=00 1 234 , 

// UNIT=2400-2 

//SYSUT2 DD DSNAME=OUTSTRM,UNIT=2400-2,DISP=( NEW, KEEP), 

// DCB=( DEN- 1 , RECFM=F , LRECL=80 , BLKSIZE=80 , TRTCH=C ) , 

// LABEL=( 2,SL) 

//SYSIN DD * 

EDIT START-JOBA , TYPE-INCLUDE , STEPNAME=STEPC , STEPD 
EDIT START=JOBB , TYPE=INCLUDE , STEPNAME=STEPE 
EDIT START-JOBC , TYPE-INCLUDE , STEPNAME=STEPJ 

/* 

The control statements are discussed below: 

• SYSUTl DD defines the input data set. The data set resides on a 7 -track, 
standard labeled tape volume (001234). 

• SYSUT2 DD defines the output data set. The data set is to reside as the second 
data set on a 7-track, standard labeled tape volume (001235). 

• SYSIN DD defines the control data set, which follows in the input stream. 

• The EDIT statements copy the indicated JOB statements and job steps. 



This example copies: (1) the JOB statement and steps STEPF and STEPG for JOBB 
and (2) the JOB statement and STEPH, excluding STEPJ, for JOBC. The input data 
set contains three jobs: JOBA, which includes STEPA, STEPB, STEPC, and STEPD; 
JOBB, which includes STEPE, STEPF, and STEPG; and JOBC, which includes STEPH 
and STEPJ. 

The example follows: 

//EDIT3 JOB 09#440, SMITH 

// EXEC PGM=IEBEDIT 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=INSET,UNIT=2314,DISP=(OLD,KEEP), 

// VOLUME=SER=231400 

//SYSUT2 DD DSNAME=OUTTAPE,UNIT=2400,LABEL( ,NL), 

// DCB=(DEN=2,RECFM=F,LRECL=80,BLKSIZE=80 ),DISP=( ,KEEP) 

//SYSIN DD * 

EDIT START-JOBB , TYPE=INCLUDE , STEPNAME=STEPF-STEPG 
EDIT START=JOBC , TYPE=EXCLUDE , STEPNAME=STEPJ 

/* 

The control statements are discussed below: 

• SYSUTl DD defines the input data set. The data set resides on a 2314 volume 
(231400). 

• SYSUT2 DD defines the output data set. The data set is to reside as the first or 
only data set on an unlabeled, 9-track (800 bits per inch) tape volume. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• The EDIT statements copy selected JOB statements and job steps. 



This example copies the JOBA JOB statement, the job step STEPF, and all the 
steps that follow it. The input data set contains one job (JOBA), which includes 
STEPA, STEPB, . . . STEPL. Job steps STEPA through STEPE are not included in 
the output data set. 
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IEBEDIT Example 5 



IEBEDIT Example 6 



The example follows: 

//EDIT4 JOB 09#440, SMITH 

// EXEC PGM=IEBEDIT 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=INSTREAM,UNIT=2314,DISP=( OLD, KEEP), 

// VOLUME=SER=231400 

//SYSUT2 DD DSNAME=OUTSTREM,UNIT=2314,DISP=( ,KEEP), 

// DCB=(RECFM=F,LRECL=80,BLKSIZE=80 ) , VOLUME=SER=23 1 40 1 , 

// SPACE=(TRK,2 ) 

//SYSIN DD * 

EDIT START=JOBA,TYPE=POSITION,STEPNAME=STEPF 
/* 

The control statements are discussed below: 

• SYSUTl DD defines the input data set. The data set resides on a 2314 or 2319 
volume (231400). 

• SYSUT2 DD defines the output data set. The data set is to reside on a 2314 
volume (231401). Two tracks are allocated for the output data set. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• EDIT copies the JOB statement and job steps STEPF through STEPL. 



This example copies the entire input (SYSUTl) data set. The record containing the 
characters "..*" in columns 1 through 3 is converted to a "/* t>" statement in the 
output data set. 

The example follows: 

//EDIT5 JOB 09#440, SMITH 

// EXEC PGM=IEBEDIT 

//SYSPRINT DD SYSOUT=A 

//SYSUT2 DD DSNAME=OUTTAPE,UNIT=2400,VOLUME=SER=001234, 

// DCB=( RECFM=F , LRECL=80 , BLKSIZE=80 ) , DISP=( NEW, KEEP ) 

//SYSIN DD DUMMY 

//SYSUT1 DD DATA 

//BLDGDGIX JOB 

// EXEC PGM=IEHPROGM 

//SYSPRINT DD SYSOUT=A 

//DD1 DD UNIT=2314,VOLUME=SER=111111 f DISP=OLD 

//SYSIN DD * 

BLDG INDEX=A . B . C , ENTRIES= 1 , EMPTY 
. * 

The control statements are discussed below: 

• SYSUT2 DD defines the output data set. The data set is to reside as the first 
data set on a 9-track tape volume (001234). 

• SYSIN DD defines a dummy control data set. 

• SYSUTl DD defines the input data set, which follows in the input stream. The 
job is terminated when the termination statement (/*b) is encountered. 



This example copies the entire input (SYSUTl) data set including the JES2 control 
statement since a new delimiter (JP) has been coded. Otherwise the "/*" in the 
JES2 control statement would have terminated the input. 
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The example follows: 

//EDIT6 JOB 09#440, SMITH 

//STEPA EXEC PGM=IEBEDIT - 

//SYSPRINT DD SYSOUT=A 

//SYSUT2 DD DSN=TAPEOUT,UNIT=2400-3,VOL=SER=0012 34, 

// LABEL=( , SL),DCB=(RECFM=FB,LRECL=80,BLKSIZE=800 ), 

// DISP=( NEW, KEEP ) 

//SYSIN DD DUMMY 

//SYSUT1 DD DATA,DLM=JP 

//LISTVTOC JOB 09#550,BLUE 

/*MESSAGE JOB NEEDS VOLUME 231400 

//FSTEP EXEC PGM=IEHLIST 

//SYSPRINT DD SYSOUT=A 

//DD2 DD UNIT^2314,VOL=SER=231400,DISP=OLD 

//SYSIN DD * 

LISTVTOC FORMAT, VOL=23 14=23 1400 

/* 
JP 

The control statements are discussed below: 

• SYSUT2 DD defines the output data set. The data set will be the first data set 
on a 9-track, standard label tape volume (001234). 

• SYSIN DD defines a dummy control data set. 

• SYSUT1 DD defines the input data set. The DLM parameter defines characters 
JP to act as a delimiter for the input data. 

• edit copies the JOB statement through the "/* "statement. 



IEBEDIT Program 8-7 



IEBGENER Program 



IEBGENER is a data set utility used to copy a sequential data set or a partitioned 
member, or to create a partitioned data set from a sequential or partitioned 
member used as input. (See "Introduction" for general data set utility 
information.) IEBGENER can be used to expand an existing partitioned data set 
by creating partitioned members and merging them into the data set that is to be 
expanded. 

IEBGENER provides optional editing facilities and exits for user routines that 
process labels, manipulate input data, create keys, and handle permanent 
input/output errors. Refer to "Appendix A: Exit Routine Linkage" for a 
discussion of linkage conventions that are applicable when user routines are 
provided. 

IEBGENER can be used to: 

• Create a backup copy of a sequential data set or a partitioned member. 

• Produce a partitioned data set from sequential input. 

• Expand a partitioned data set. 

• Produce an edited sequential or partitioned data set. 

• Reblock or change the logical record length of a data set. 

• Copy user labels on sequential output data sets. 

At the completion or termination of IEBGENER, the highest return code 
encountered within the program is passed to the calling program. 

Creating a Backup Copy 

A backup copy of a sequential data set or partitioned member can be produced 
by copying the data set or member to any IBM-supported output device. For 
example, a copy can be made from tape to tape, from direct access to tape, etc. 

A data set that resides on a direct access volume can be copied to its own 
volume, provided that its data set name is changed. A partitioned data set cannot 
reside on a magnetic tape volume. 

Producing a Partitioned Data Set from Sequential Input 

IEBGENER can be used to produce a partitioned data set from sequential output. 
Through the use of utility control statements, the user can logically divide the 
sequential data set into record groups and assign member names to the record 
groups. IEBGENER places the newly created members in a partitioned output data 
set. 

Note: A partitioned data set cannot be produced if an input or output data set 
contains spanned records. 

Figure 9-1 shows how a partitioned data set is produced from a sequential data 
set used as input. The left-hand side of the figure shows the sequential data set. 
Utility control statements are used to divide the sequential data .set into record 
groups and to provide a member name for each record group. The right-hand 
side of the figure shows the partitioned data set produced from the sequential 
input. 
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Figure 9-1. Creating a Partitioned Data Set from Sequential Input Using IEBGENER 

Expanding a Partitioned Data Set 

An expanded data set is a data set into which an additional member or members 
have been merged. IEBGENER creates the members from sequential input and 
places them in the data set being expanded. The merge operation — the ordering 
of the partitioned directory — is automatically performed by the program. 

Figure 9-2 shows how sequential input is converted into members that are 
merged into an existing partitioned data set. The left-hand side of the figure 
shows the sequential input that is to be merged with the partitioned data set 
shown in the middle of the figure. Utility control statements are used to divide 
the sequential data set into record groups and to provide a member name for 
each record group. The right-hand side of the figure shows the expanded 
partitioned data set. Note that members B, D, and E from the sequential data set 
were placed in available space and that they are sequentially ordered in the 
partitioned directory. 

Producing an Edited Data Set 

IEBGENER can be used to produce an edited sequential or partitioned data set. 
Through the use of utility control statements, the user can specify editing 
information that applies to a record, a group of records, selected groups of 
records, or an entire data set. 

An edited data set can be produced by: 

• Rearranging or omitting defined 4ata fields within a record. 

• Supplying literal information as replacement data. 
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• Converting data from packed decimal to unpacked decimal mode, unpacked 
decimal to packed decimal mode, or H-set BCD to EBCDIC mode. 
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Figure 9-2. Expanding a Partitioned Data Set Using iebgener 

Figure 9-3 shows part of an edited sequential data set. The left-hand side of the 
figure shows the data set before editing is performed. Utility control statements 
are used to identify the record groups to be edited and to supply editing 
information. In this figure, literal replacement information is supplied for 
information within a defined field. (Data is rearranged, omitted, or converted in 
the same manner.) The BBBB field in each record in the record group is to be 
replaced by CCCC. The right-hand side of the figure shows the data set after 
editing. 
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Figure 9-3. Editing a Sequential Data Set Using iebgener 
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Note: IEBGENER cannot be used to edit a data set if the input and output data 
sets consist of VS or VBS records and have equal block sizes and logical record 
lengths. In this case, any utility control statements that specify editing are 
ignored; IEBGENER performs a straight copy; that is, for each physical record 
read from the input data set, the utility writes an unedited physical record on the 
output data set. 

Reblocking or Changing Logical Record Length 

IEBGENER can be used to produce a reblocked output data set containing either 
fixed or variable records. In addition, the program can produce an output data 
set having a logical record length that differs from the input logical record length. 



Input and Output 



Controll 



IEBGENER uses the following input: 

• An input data set, which contains the data that is to be copied, edited, 
converted into a partitioned data set, or converted into members to be merged 
into an existing data set. The input is either a sequential data set or a member 
of a partitioned data set. 

• A control data set, which contains utility control statements. The control data 
set is required if editing is to be performed or if the output data set is to be a 
partitioned data set. 

IEBGENER produces the following output: 

• An output data set, which can be either sequential or partitioned. The output 
data set can be either a new data set (created during the current job step) or 
an existing partitioned data set that is to be expanded. 

• A message data set, which contains informational messages (for example, the 
contents of utility control statements) and any error messages. 

IEBGENER provides a return code to indicate the results of program execution. 
The return codes and their meanings are: 

• 00, which indicates successful completion. 

• 04, which indicates probable successful completion. A warning message is 
written. 

• 08, which indicates that processing was terminated after the user requested 
processing of user header labels only. 

• 12, which indicates an unrecoverable error. The job step is terminated. 

• 16, which indicates that a user routine passed a return code of 16 to 
IEBGENER. The job step is terminated. 



IEBGENER is controlled by job control statements and utility control statements. 
The job control statements are required to execute or invoke IEBGENER and to 
define the data sets that are used and produced by the program. The utility 
control statements are used to control the functions of IEBGENER. 



Job Control Statements 



Table 9-1 shows the job control statements necessary for using IEBGENER. 
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Restrictions 



Table 9-1. IEBGENER Job Control Statements 

Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (PGM=IEBGENER) or, if the job control 

statements reside in a procedure library, the procedure name. 

SYSPRINT DD Defines a sequential message data set. The data set can be written to a 
system output device, a tape volume, or a direct access volume. 

SYSUT1 DD Defines the input data set. It can define a sequential data set or a member 

of a partitioned data set. 

SYSUT2 DD Defines the output data set. It can define a sequential data set, a member of 

a partitioned data set, or a partitioned data set. 

SYSIN DD Defines the control data set, or specifies DUMMY when the output is 

sequential and no editing is specified. The control data set normally resides 
in the input stream; however, it can be defined as a member within a 
library of partitioned members. 

IEBGENER always uses two buffers, regardless of what was specified in the DCB. 

If both the SYSUTl and the SYSUT2 DD statements specify standard user labels 
(SUL), IEBGENER copies user labels from SYSUTl to SYSUT2. See "Appendix D: 
Processing User Labels" for a discussion of the available options for user label 
processing. 

Both the input data set and the output data set can contain fixed, variable, 
undefined, or variable spanned records. These records can be reblocked by the 
specification of a new maximum block length on the SYSUT2 DD statement. 
During reblocking, if the output data set resides on a direct access volume: 

• For fixed or variable records, keys can be retained only by using the 
appropriate user exit. 

• For variable spanned records, keys can never be retained. 

Refer to OS/VS Data Management Services Guide, GC26-3783, for information on 
estimating space allocations. 



The SYSPRINT DD statement is required for each use of IEBGENER. 

The block size for the SYSPRINT data set must be a multiple of 121. The 
block size for the SYSIN data set must be a multiple of 80. Any blocking 
factor can be specified for these block sizes. 

Space must be allocated for an output data set (SYSUT2 DD statement) that is 
to reside on a direct access device unless the data set is an expanded data, set, 
in which case space must not be allocated. 

If the output data set is on a card punch or a printer, the user must specify 
DCB information on the SYSUT2 DD statement. DCB parameters in a SYSUT2 
DD statement defining an expanded partitioned data set must be compatible 
with the specifications made when the data set was originally created. 

The SYSIN DD statement is required for each use of IEBGENER. 

Concatenated data sets with unlike attributes are not allowed as input to 
IEBGENER. For information on concatenated data sets, see OS/VS Data 
Management Services Guide, GC26-3783. 

When RECFM, BLKSIZE, and LRECL are not specified in the JCL for the input 
data set, values for each are copied from the input data set's DSCB. 

Always specify the output block size when the logical record length and record 
format (except for u) are specified. The default RECFM is U for the output 
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data set. The output LRECL must be specified when editing is to be performed 
and the record format is FB, vs, or VBS. In all other cases, a default LRECL 
value is generated by IEBGENER. 

• The input data set must always have a BLKSIZE parameter specified. The 
default RECFM is U for the input data set. The input LRECL must be specified 
when the record format is FB, VS, or VBS. In all other cases, a default LRECL 
is generated by IEBGENER. 

Utility Control Statements 

IEBGENER is controlled by utility control statements. The statements and the 
order in which they must appear are: 

• GENERATE statement, which is used to indicate the number of member names 
and alias names, record identifiers, literals, and editing information contained 
in the control data set. 

• EXITS statement, which is used to indicate that user routines are provided. 

• LABELS statement, which is used to specify user-label processing. 

• MEMBER statement, which is used to specify the member name and alias of a 
member of a partitioned data set to be created. 

• RECORD statement, which is used to define a record group to be processed 
and to supply editing information. 

The control statements are included in the control data set as required. If no 
utility control statements are included in the control data set, the entire input 
data set is copied sequentially. 

When the output is to be sequential and editing is to be performed, one 
GENERATE statement and as many RECORD statements as required are used. If 
user exits are provided, an EXITS statement is used. 

When the output is to be partitioned, one GENERATE statement, one member 
statement per output member, and RECORD statements, as required, are used. If 
user exits are provided, an EXITS statement is used. 



GENERATE Statement 



The GENERATE statement is used when: (1) output is to be partitioned, (2) 
editing is to be performed, or (3) user routines are provided and/or label 
processing is specified. 

The GENERATE statement must appear before other statements. If it contains 
errors or is inconsistent with other statements, IEBGENER is terminated. 

The format of the GENERATE statement is: 



[label] GENERATE 



[MAXNAME=n] 
[,MAXFLDS=n] 
[,MAXGPS=n] 
[,MAXLITS=n] 



where: 



MAXNAME=n 

specifies a number that is no less than the total number of member names and 
aliases appearing in subsequent MEMBER statements. MAXNAME is required if 
there are one or more MEMBER statements. 
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EXITS Statement 



MAXFLDS=n 

specifies a number that is no less than the total number of FIELD parameters 
appearing in subsequent RECORD statements. MAXFLDS is required if there are 
any field parameters in subsequent RECORD statements. 

MAXGPS=n 

specifies a number that is no less than the total number of IDENT parameters 
appearing in subsequent RECORD statements. MAXGPS is required if there are 
any IDENT parameters in subsequent RECORD statements. 

MAXLITS=n 

specifies a number that is no less than the total number of characters 
contained in the field literals of subsequent RECORD statements. MAXLITS is 
required if the FIELD parameters of subsequent RECORD statements contain 
literals. MAXLITS does not pertain to literals used in IDENT parameters. 



The EXITS statement is used to identify exit routines supplied by the user. 
Linkages to and from exit routines are discussed in "Appendix A: Exit Routine 
Linkage." 

The EXITS statement is used when user routines are provided. 

The format of the EXITS statement is: 

[label] EXITS [INHDR= routi nename] 

[,OUTHDR= routinename] 
[,INTLR = routinename] 
[,OUTTLR= routinename] 
[,KE Y = routinename] 
[,D ATA= routinename] 
[,IOERROR= routinename] 
[,TOT AL= (routinename,size)] 

where: 

INHDR= routinename 

specifies the symbolic name of a routine that processes user input header 
labels. 

OUTHDR = routinename 

specifies the symbolic name of a routine that creates user output header labels. 
OUTHDR is ignored if the output data set is partitioned. 

INTLR = routinename 

specifies the symbolic name of a routine that processes user input trailer 
labels. 

OUTTLR= routinename 

specifies the symbolic name of a routine that processes user output trailer 
labels. OUTTLR is ignored if the output data set is partitioned. 

KEY = routinename 

specifies the symbolic name of a routine that creates the output record key. 
(This routine does not receive control when a data set consisting of VS or VBS 
type records is processed because no processing of keys is permitted for this 
type of data.) 
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LABELS Statement 



DATA = routinename 

specifies the symbolic name of a routine that modifies the physical record 
(logical record for vs or VBS type records) before it is processed by 

IEBGENER. 

lOERROR=routinename 

specifies the symbolic name of a routine that handles permanent input/output 
error conditions. 

TOTAL= 

specifies that exits to a user's routine are to be provided prior to writing each 
record. The keyword OPTCD=T must be specified for the SYSUT2 DD 
statement. TOTAL is valid only when the utility is used to process sequential 
data sets. These values must be coded: 

routinename 

specifies the name of a user-supplied totaling routine. 

size 

specifies the number of bytes needed to contain totals, counters, pointers, 
etc. 

For a detailed discussion of the processing of user labels as data set descriptors, 
and for discussion of user label totaling, refer to "Appendix D: Processing User 
Labels." 



The LABELS statement specifies whether or not user labels are to be treated as 
data by IEBGENER. For a detailed discussion of this option, refer to "Processing 
User Labels as Data," in "Appendix D: Processing User Labels." 

The LABELS statement is used when the user wants to specify that: (1) no user 
labels are to be copied to the output data set, (2) user labels are to be copied to 
the output data set from records in the data portion of the SYSIN data set, or (3) 
user labels are to be copied to the output data set after they are modified by the 
user's label processing routines. If more than one valid labels statement is 
included, all but the last LABELS statement are ignored. 

The format of the LABELS statement is: 



[label] LABELS [DATA= 



{ YES } 
{NO} 
{ALL} 
{ONLY} 

{INPUT}] 



where: 



DATA= 

specifies whether user labels are to be treated as data by IEBGENER. These 
values can be coded: 

YES 

specifies that any user labels that are not rejected by a user's label 
processing routine are to be treated as data. Processinf of labels as data 
ends in compliance with standard return codes. If no value is entered, YES 
is assumed. 



NO 



specifies that user labels are not to be treated as data. 
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MEMBER Statement 



RECORD Statement 



ALL 

specifies that user labels in the group currently being processed are to be 
treated as data regardless of any return code. A return code of 16 causes 
IEBGENER to complete processing the remainder of the group of user labels 
and to terminate the job step. 

ONLY 

specifies that only user header labels are to be treated as data. User header 
labels are processed as data regardless of any return code. The job 
terminates upon return from the OPEN routine. 

INPUT 

specifies that user labels for the output data set are supplied as 80-byte 
input records in the data portion of SYSIN. The number of input records 
that should be treated as user labels must be identified by a RECORD 
statement. 

Note: LABELS DATA=NO must be specified to make standard user labels (SUL) 
exits inactive when input/output data sets with nonstandard labels (NSL) are 
to be processed. 



The MEMBER statement is used when the output is to be partitioned. One 
MEMBER statement must be included for each member to be created by 
IEBGENER. The MEMBER statement provides the name and aliases of a member 
that is to be created. 

All RECORD statements following a MEMBER statement pertain to the member 
named in that MEMBER statement. If no MEMBER statements are included, the 
output data set is organized sequentially. 

The format of the MEMBER statement is: 

[label] MEMBER NAME=(name[,a//asJ...) 

where: 

NAME=(name[,a//asJ...) 

specifies a member name followed by a list of its aliases. If only one name 
appears in the statement, it need not be enclosed in parentheses. 



The RECORD statement is used to define a record group and to supply editing 
information. A record group consists of records that are to be processed 
identically. 

The RECORD statement is used when: (1) the output is to be partitioned, (2) 
editing is to be performed, or (3) user labels for the output data set are to be 
created from records in the data portion of the SYSIN data set. The RECORD 
statement defines a record group by identifying the last record of the group with 
a literal name. 

If no RECORD statement is used, the entire input data set or member is processed 
without editing. More than one RECORD statement may appear in the control 
statement stream for IEBGENER. 

Within a RECORD statement, one IDENT parameter can be used to define the 
record group; one or more FIELD parameters can be used to supply the editing 
information applicable to the record group; and one LABELS parameter can be 
used to indicate that this statement is followed immediately by output label 
records. 
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The format of the RECORD statement is: 

{[label] RECORD [IDENT= {length, l name\input-location)]\ 

{ [ ,FIELD =([length] [ ,'mput- location] [ conversion] 
[ ,output - location] [ Jiterar ] } 

{[,LABELS=n]} 
where: 

IDENT= 

identifies the last record of the input group to which the FIELD parameters or 
MEMBER statement applies. If the RECORD statement is not followed by 
additional RECORD or MEMBER statements, IDENT also defines the last record 
to be processed. If IDENT is omitted, the remainder of the input data is 
considered to be in one record group; subsequent RECORD and MEMBER 
statements are ignored. These values can be coded: 

length 

specifies the length (in bytes) of the identifying name. The length cannot 
exceed eight characters. 

'name* 

specifies the exact literal that identifies the last input record of a record 
group. If no match for name is found, the remainder of the input data is 
considered to be in one record group; subsequent RECORD and MEMBER 
statements are ignored. 

input -location 

specifies the starting location of the field that contains the identifying name 
in the input records. 

FIELD = 

specifies field-processing and editing information. Only the contents of 
specified fields in the input record is copied to the output record. The values 
that can be coded are: 

length 

specifies the length (in bytes) of the input field or literal to be processed. If 
length is not specified, a length of 80 bytes is assumed. If a literal is to be 
processed, a length of 40 bytes or less must be specified. 

input-location 

specifies the starting byte of the field to be processed. If input -location is not 
specified, byte 1 is assumed. 

'literal* 

specifies a literal (maximum length of 40 bytes) to be placed in the 
specified output location. If a literal contains apostrophes, each apostrophe 
must be written as two consecutive apostrophes. 

conversion 

specifies a two-byte code that indicates the type of conversion to be 
performed on this field. If no conversion is specified, the field is moved to 
the output area without change. The values that can be coded are: 

PZ 

specifies that data (packed decimal) is to be converted to unpacked 
decimal data. 

ZP 

specifies that data (unpacked decimal) is to be converted to packed 
decimal data. 
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IEBGENER Examples 



HE 

specifies that data. (H-set BCD) is to be converted to EBCDIC. 

output-location 

specifies the starting location of this field in the output records. If 
output-location is not specified, byte 1 is assumed. 

LABELS =n 

is an optional parameter that indicates the number of records in the SYSIN 
data set to be treated as user labels. The number n, which is a number from 1 
to 8, must specify the exact number of label records that follow the RECORD 
statement. If this parameter is included, DATA=INPUT must be coded on a 
LABELS statement before it in the input stream. 

If conversion is specified in FIELD, the following restrictions apply: 

• PZ-type (packed-to-unpacked) conversion is impossible for packed decimal 
records longer than 16K bytes. 

• For ZP-type (unpacked-to-packed) conversion, the normal 32K-byte maximum 
applies. 

• When the ZP parameter is specified, the conversion is performed in place. The 
original unpacked field is replaced by the new packed field. Therefore, the ZP 
parameter must be omitted from subsequent references to that field. If the 
field is needed in its original unpacked form, it must be referenced prior to the 
use of the ZP parameter. 

If conversionAs specified in the FIELD parameter, the length of the output record 
can be calculated for each conversion specification. When L is equal to the length 
of the input record, the calculation is made, as follows: 

• For a PZ (packed-to-unpacked) specification, 2L - 1 . 

• For a ZP (upacked-to-packed) specification, (L/2) + C. If L is an odd 
number, C is 1/2; if L is an even number, c is 1. 

• For an (H-set BCD to EBCDIC) specification, L. 

If both output header labels and output trailer labels are to be contained in the 
SYSIN data set, the user must include one RECORD statement (including the 
LABELS parameter), indicating the number of input records to be treated as user 
labels, for header labels and one for trailer labels. The first such RECORD 
statement indicates the number of user header labels; the second indicates the 
number of user trailer labels. If only output trailer labels are included in the 
SYSIN data set, a RECORD statement must be included to indicate that there are 
no output header labels in the SYSIN data set (LABELS=0). This statement must 
precede the RECORD LABELS=n statement which signals the start of trailer label 
input records. 

For a detailed discussion of the LABELS option, refer to "Processing User Labels 
As Data," in "Appendix D: Processing User Labels." 

Note: IDENT and FIELD parameters are ignored in straight copy processing of 
data sets that contain vs or VBS records. 



The examples that follow illustrate some of the uses of IEBGENER. Table 9-2 can 
be used as a quick reference guide to IEBGENER examples. The numbers in the 
"Example" column point to the examples that follow. 
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IEBGENER Example 1 



Table 9-2. 


iebgener Example Directory 




Operation 


Data Set 
Organization 


Devices 


Comments 


Example 


COPY 


Sequential 


Card Reader, 
Tape 


Blocked output. 


l 


COPY-with 
editing 


Sequential 


Card Reader, 
Tape 


Blocked output. 


2 


COPY-with 
editing 


Sequential 


Card Reader, 
Tape 


Blocked output. Input includes 
// cards. 


3 


COPY-with 
editing 


Sequential 


Card Reader, 
2314 Disk 


Blocked output. Input includes 
// cards. 


4 


PRINT 


Sequential 


Card Reader, 
Printer 


Input includes // cards. System 
output device is a printer. 


5 


CONVERT 


Sequential 
input, 
Partitioned 
output 


Tape, 
2314 Disk 


Blocked output. Three members 
are to be created. 


6 


COPY-with 
editing 


Sequential 


3330 Drum 


Blocked output. Two members are 
to be merged into existing data set. 


7 


COPY-with 
editing 


Sequential 


Tape 


Blocked output. Data set edited as 
one record group. 


8 


COPY-with 
editing 


Sequential 


2314 Disk 


Blocked output. New record length 
specified for output data set. Two 
record groups specified. 


9 


COPY-with 
editing 


Sequential 


Tape 


Blocked output. Data set edited as 
one record group. 


10 



IEBGENER Example 2 



In this example, a card-input, sequential data set is to be copied to a 9-track tape 
volume. 

The example follows: 

//CDTOTAPE JOB 09#660, SMITH 

// EXEC PGM= IEBGENER 

//SYSPRINT DD SYSOUT^A 

//SYSIN DD DUMMY 

//SYSUT2 DD DSNAME=OUTSET,UNIT=2400,LABEL=( , SL) , 

// DISP=( , KEEP ),VOLUME=SER=001 234, DCB=(RECFM=FB, 

// LRECL=80,BLKSIZE=2000 ) 

//SYSUT1 DD * 

(input card data set) 

/* 

The control statements are discussed below: 

• SYSIN DD defines a dummy data set. No editing is to be performed; therefore, 
no utility control statements are needed. 

• SYSUT2 DD defines the output data set. The data set is written to a 9-track 
tape volume at a density of 800 bits per inch. The data set is to reside as the 
first (or only) data set on the volume. 

• SYSUTl DD defines the card-input data set. The data set can contain no // 
cards. 



In this example, a card-input, sequential data set is to be copied to a 7-track tape 
volume. The control data set is a member of a partitioned data set. 
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IEBGENER Example 3 



IEBGENER Example 4 



The example follows: 

//CDTOTAPE JOB 09#660, SMITH 

// EXEC PGM=IEBGENER 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD DSNAME=CNTRLIBY( STMNTS ),UNIT=2314, 

// DISP=( OLD, KEEP ) , VOLUME=SER=1 1 1 1 1 2 ,DCB=( RECFM=F , 

// LRECL=80,BLKSIZE=80 ) 

//SYSUT2 DD DSNAME=OUTSET,UNIT=2400-2,LABEL=( , SL ) , 

// DCB=(DEN=1 ,RECFM=FB,LRECL=80,BLKSIZE=2000,TRTCH=C), 

// DISP=( , KEEP ),VOLUME=SER=00 1234 

//SYSUT1 DD * 

(input card data set) 

/* 

The control statements are discussed below: 

• SYSIN DD defines the control data set, which contains the utility control 
statements. The control statements reside as a member, STMNTS, in a 
partitioned data set. 

• SYSUT2 DD defines the output data set. The data set is written as the first or 
only data set on the volume. It is written at a density of 556 bits per inch on 
a 7 -track tape volume. 

• SYSUTi DD defines the card-input data set. The data set can contain no // 
cards. 



In this example, a card-input, sequential data set is to be copied to a 9-track tape 
volume. The input contains cards that have slashes (//) in columns 1 and 2. The 
control data set is a member of a partitioned data set. 

The example follows: 

//CDTOTAPE JOB 09#660, SMITH 

// EXEC PGM=IEBGENER 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD DSNAME=CNTRLIBY( STMNTS ),UNIT=2314, 

// DISP=( OLD, KEEP ) , VOLUME=SER=1 11112, 

// DCB=(RECFM=F,LRECL=80,BLKSIZE=80 ) 

//SYSUT2 DD DSNAME=OUTSET,UNIT=2400,LABEL=( 2 , SL ) , 

// VOLUME=SER=00 1234, DCB=( RECFM=FB , LRECL=80 , 

// BLKSIZE=2000 ),DISP=( ,KEEP) 

//SYSUT1 DD DATA 

(input card data set, including // cards) 

/* 

The control statements are discussed below: 

• SYSIN DD defines the data set containing the utility control statements. The 
statements reside as a member, STMNTS, in a partitioned data set. 

• SYSUT2 DD defines the copied sequential data set (output). The data set is 
written as the second data set on the specified tape volume. 

• SYSUTi DD defines the card-input data set. The data set is to be edited as 
specified in the utility control statements (not shown). The input data set 
contains // cards. 



In this example, a card-input, sequential data set is to be copied to a 2314 
volume. The input data set contains // cards. 
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IEBGENER Example 5 



IEBGENER Example 6 



The example follows: 

//CDTODISK JOB 09#660, SMITH 

// EXEC PGM=IEBGENER 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD DSNAME=-CNTRLIBY( STMNTS ),UNIT=2314, 

// DISP=( OLD, KEEP ) , VOLUME=SER=1 11112, 

// DCB=(RECFM=F,LRECL=80,BLKSIZE=80 ) 

//SYSUT2 DD DSNAME=OUTSET,UNIT=2314,VOLUME=SER=1 1 1 1 13, 

// DISP=( ,KEEP),SPACE=(TRK,( 10,10) ) ,DCB=( RECFM=FB, 

// LRECL=80,BLKSIZE=2000) 

//SYSUT1 DD DATA 

(input card data set, including // cards) 

/* 

The control statements are discussed below: 

• SYSIN DD defines the control data set, which contains the utility control 
statements. The control statements reside as a member, STMNTS, in a 
partitioned data set. 

• SYSUT2 DD defines the output data set. Ten tracks of primary storage space 
and ten tracks of secondary space are allocated for the data set on a 2314 
volume. 

• SYSUTl DD defines the card-input data set. The data set is to be edited as 
specified in the utility control statements (not shown). The input data set 
contains // cards. 



In this example, the content of a card data set is to be printed. The printed 
output is to be left-aligned, with one 80-byte record appearing on each line of 
printed output. 

The example follows: 

//CDTOPTR JOB 09#660, SMITH 

// EXEC PGM=IEBGENER 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD DUMMY 

//SYSUT2 DD SYSOUT=A,DCB=(RECFM=F / LRECL=80,BLKSIZE=80) 

//SYSUT1 DD DATA 

(input card data set, including // cards) 

/* 

The control statements are discussed below: 

• SYSIN DD defines a dummy data set. No editing is to be performed; therefore, 
no utility control statements are required. 

• SYSUT2 DD indicates that the output is to be written on the system output 
device (printer). Carriage control can be specified by changing the RECFM=F 
subparameter to RECFM=FA. 

• SYSUTl DD defines the input card data set. The input data set contains // 
cards. 



In this example, a partitioned data set (consisting of three members) is to be 
created from sequential input. 

The example follows: 
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//TAPEDISK JOB 09#660, SMITH 

// EXEC PGM=IEBGENER 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=INSET,UNIT=2400,LABEL=( , SL ) , 

// DISP=( OLD , KEEP ) , VOLUME=SER=00 1234, DCB=( RECFM=F, 

// LRECL=80,BLKSIZE=80 ) 

//SYSUT2 DD DSNAME=NEWSET,UNIT=2314,DISP=( ,KEEP), 

// VOLUME=SER=1 1 1 1 1 2 , SPACE=( TRK, ( 10,5,5 ) ), 

// DCB=(RECFM=FB,LRECL=80,BLKSIZE=2000 ) 

//SYSIN DD * 

GENERATE MAXNAME=3 , MAXGPS=2 

MEMBER NAME=MEMBER1 
GROUP 1 RECORD IDENT=( 8, 'FIRSTMEM' , 1 ) 

MEMBER NAME-MEMBER2 
GROUP2 RECORD IDENT=( 8 , ' SECNDMEM' , 1 ) 

MEMBER NAME=MEMBER3 
/* 

The control statements are discussed below: 

• SYSUTi dd defines the input data set (INSET). The data set was originally 
written on a 9-track tape volume at a density of 800 bits per inch. 

• SYSUT2 dd defines the output partitioned data set (NEWSET). The data set; is 
to be placed on a 2314 volume. Ten tracks of primary space, five tracks of 
secondary space, and five blocks (256 bytes each) of directory space are 
allocated to allow for future expansion of the data set. The output records are 
blocked to reduce the space required by the data set. 

• SYSIN DD defines the control data set, which follows in the input stream. The 
utility control statements are used to create members from sequential input 
data; the statements do not specify any editing. 

• generate indicates that: (1) three member names are included in subsequent 
MEMBER statements and (2) the IDENT parameter appears twice in subsequent 
RECORD statements. 

• The first member statement assigns a member name (MEMBER l) to the first 
member. 

• The first RECORD statement (GROUP l) identifies the last record to be placed 
in the first member. The name of this record (FIRSTMEM) appears in bytes 1 
through 8 of the input record. 

• The remaining MEMBER and RECORD statements define the second and third 
members. 
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IEBGENER Example 7 



In this example, sequential input is to be converted into two partitioned 
members. The newly created members are Jo be merged into an existing 
partitioned data set. User labels on the input data set are to be passed to the 
user exit routines. 

The example follows: 

//DISKTODK JOB 09#660, SMITH 

// EXEC PGM=IEBGENER 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=INSET,UNIT=3330,DISP=( OLD, KEEP), 

// VOLUME=SER=1 1 1 1 1 2 , DCB=( RECFM=FB, LRECL=80 , BLKSIZE=2000 ), 

// LABEL- ( ,SUL) 

//SYSUT2 DD DSNAME=EXISTSET,UNIT=3330,DISP=( MOD, KEEP), 

// VOLUME=SER=1 1 1 1 1 3 ,DCB=( RECFM=FB, LRECL=80 , BLKSIZE=2000 ) 

//SYSIN DD * 

MAXNAME=3 , MAXGPS= 1 

INHDR=R0UT1 , INTLR=ROUT2 

NAME=( MEMX , ALIASX ) 

IDENT=( 8 , ' FIRSTMEM ' , 1 ) 

NAME=MEMY 



GENERATE 

EXITS 

MEMBER 

GROUP 1 RECORD 

MEMBER 

/* 



The control statements are discussed below: 

• SYSUTl DD defines the input data set (INSET). The input data set, which 
resides on a 3330 volume, has standard and user labels. 

• SYSUT2 DD defines the output partitioned data set (EXISTSET). The members 
created during this job step are merged into the partitioned data set. The 
output records are blocked to reduce the space required by the new members. 

• SYSIN DD defines the control data set, which follows in the input stream. The 
utility control statements are used to- create members from sequential input 
data; the statements do not specify any editing. 

• GENERATE indicates that: (1) two member names and one alias are included 
in subsequent MEMBER statements and (2) an IDENT parameter appears in a 
subsequent RECORD statement. 

• EXITS defines the user routines that are to process user labels. 

• The first MEMBER statement assigns a member name (MEMX) and an alias 
(ALIASX) to the first member. 

• The first RECORD statement identifies the last record to be placed in the first 
member. The name of this record (FIRSTMEM) appears in bytes 1 through 8 of 
the input record. 

• The second MEMBER statement assigns a member name (MEMY) to the second 
member. The remainder of the input data set is included in this member. 
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In this example, a sequential input data set is to be edited and copied. 

The example follows: 

72 
//TAPETAPE JOB 09#660, SMITH 
// EXEC PGM=IEBGENER 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=OLDSET,UNIT=2400-2,DISP=( OLD, KEEP), 
// VOLUME=SER=0 12 34, LABEL= ( 3 , SL ) , DCB= ( RECFM=F , LRECL=80 , 
// BLKSIZE=80,TRTCH=C) 

//SYSUT2 DD DSNAME=NEWSET,UNIT=2400~2,DISP=( NEW, PASS ), 
// DCB=( RECFM=FB , LRECL=80 , BLKSIZE=2000 , TRTCH=C ) , 
// VOLUME=SER=001235,LABEL=( , SL ) 
//SYSIN DD * 

GENERATE MAXFLDS=3 , MAXLITS= 1 1 

RECORD FIELD=( 10, '**********',, 1 ), C 

FIELD=( 5 , 1 , HE , 1 1 ) , FIELD=( 1 ,' = ',, 1 6 ) 
EXITS INHDR=ROUT1 ,OUTTLR=ROUT2 
LABELS DATA=INPUT 
RECORD LABELS=2 

(first header label record) 
(second header 1 label record) 

RECORD LABELS=2 

(first trailer label record) 
(second trailer label record) 

/* 

The control statements are discussed below: 

• SYSUTl DD defines the sequential input data set (OLDSET). The data set was 
originally written as the third data set (800 bits per inch) on a 7 -track tape 
volume. 

• SYSUT2 DD defines the sequential output data set (NEWSET). The data set is 
written as the first or only data set on a 7-track tape volume. A density of 
800 bits per inch and data conversion are specified for the write operation. 
The output records are blocked to reduce the space required by the data set 
and to reduce the access time required when the data set is subsequently 
referred to. The data set is passed to a subsequent job step. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• GENERATE indicates that: (1) a maximum of three FIELD parameters is 
included in subsequent RECORD statements and (2) a maximum of 1 1 literal 
characters are included in subsequent FIELD parameters. 

• EXITS indicates that the specified user routines require control when SYSUTl is 
opened and when SYSUT2 is closed. 

• LABELS indicates that labels are included in the input stream. 

• The first RECORD statement controls the editing, as follows: (1) asterisks aire 
placed in positions 1 through 10, (2) bytes 1 through 5 of the input record are 
converted from H-set BCD to EBCDIC mode and moved to positions 1 1 
through 15, and (3) an equal sign is placed in byte 16. 

• The second RECORD statement indicates that the next two records from SYSIN 
should be written out as user header labels on SYSUT2. 

• The third RECORD statement indicates that the next two records from SYSIN 
should be written as user trailer labels on SYSUT2. 
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Note: This example shows the relationship between the RECORD LABELS 
statement and the exits statement, iebgener attempts to write a first and 
second label trailer as user labels at close time of SYSUT2 before returning 
control to the system; the user routine, ROUT2, can review these records and 
change them, if necessary. 



In this example, a sequential input data set is to be edited and copied. 
The example follows: 

//DISKDISK JOB 09#660, SMITH 

// EXEC PGM=IEBGENER 

//SYSPRINT DD SYSOUT-A 

//SYSUT'I DD DSNAME=OLDSET,UNIT=2314,DISP=( OLD, KEEP), 

// VOLUME=SER=1 1 1 1 1 2 , DCB=( RECFM=F, LRECL=1 00 , BLKSIZE=1 00 ) 

//SYSUT2 DD DSNAME=NEWSET,UNIT=2314,DISP=(NEW,KEEP), 

// VOLUME=SER=1 1 1 1 1 3 , DCB=( RECFM=FB, LRECL=80 , 



72 



// BLKSIZE=640 

//SYSIN DD 

GENERATE 

EXITS 

GROUP 1 RECORD 



GROUP 2 
/* 



RECORD 



,SPACE=(TRK,( 20, 10 ) ) 
* 

MAXFLDS=4 , MAXGPS= 1 
I OERROR= ERRORRT 
IDENT=( 8 , ' FIRSTGRP ' , 1 ) , 
FIELD=( 21 ,80, ,60 ),FIELD=( 59, 1 , 
FIELD=( 1 1 , 90 , , 70 ) , FIELD=( 69 , 1 



) 
1 ) 



The control statements are discussed below: 



SYSUTl DD defines the input data set (OLDSET). The logical record length of 
the input records is 100 bytes. 

SYSUT2 DD defines the output data set (OUTSET). Twenty tracks of primary 
storage space and ten tracks of secondary storage space are allocated for the 
data set on a 2314 volume. The logical record length of the output records is 
80 bytes, and the output is blocked. 

SYSIN DD defines the control data set, which follows in the input stream. 

GENERATE indicates that: (1) a maximum of four FIELD parameters is 
included in subsequent RECORD statements and (2) a maximum of one IDENT 
parameter appears in a subsequent RECORD statement. 

EXITS identifies the user routine that handles input/output errors. 

The first RECORD statement controls the editing of the first record group, as 
follows: (1) FIRSTGRP, which appears in bytes 1 through 8 of the input 
record, is defined as being the last record in the first group of records and (2) 
bytes 80 through 100 of each input record are moved into positions 60 
through 80 of each corresponding output record. (This example implies that 
bytes 60 through 79 of the input records in the first record group are no 
longer required; thus, the logical record length is shortened by 20 bytes.) The 
remaining bytes within each input record are transferred directly to the output 
records, specified in the second FIELD parameter. 

The second RECORD statement indicates that the remainder of the input 
records are to be processed as the second record group. Bytes 90 through 100 
of each input record are moved into positions 70 through 80 of the output 
records. (This example implies that bytes 70 through 89 of the input records 
from group 2 are no longer required; thus, the logical record length is 
shortened by 20 bytes.) The remaining bytes within each input record are 
transferred directly to the output records, specified in the second FIELD 
parameter. 
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IEBGENER Example 10 



If the logical record length of the output data set differs from that of the input 
data set, as in this example, all positions in the output records must undergo 
editing to justify the new logical record length. 



In the example, a sequential input data set is to be edited and copied. 

The example follows: 

72 
//TAPETAPE JOB 09#660, SMITH 
// EXEC PGM=IEBGENER 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=OLDSET,UNIT=2400,DISP=( OLD, KEEP), 
// VOLUME=SER=001234,LABEL=( 3 , SUL ) ,DCB=( RECFM=F , 
// LRECL=80,BLKSIZE=80 ) 

//SYSUT2 DD DSNAME=NEWSET,UNIT=2400,DISP=( NEW, PASS ), 
// VOLUME=SER=001235,LABEL=( , SUL ) ,DCB=( RECFM=FB, 
// LRECL=80,BLKSIZE=2000 ) 
//SYSIN DD * 

GENERATE MAXFLDS=3 , MAXLITS= 1 1 

RECORD FIELD=( 10, '**********',, 1 ), C 

FIELD=( 5, 1 , HE, 1 1 ),FIELD=( 1 ,' = ',, 16) 

LABELS DATA= INPUT 

RECORD LABELS=3 

(first header label record) 
(second header label record) 
(third header label record) 

RECORD LABELS=2 

(first trailer label record) 
(second trailer label record) 

/* 

The control statements are discussed below: 

• SYSUTl DD defines the input data set (OLDSET). The data set was originally 
written as the third data set (800 bits per inch) on a 9-track tape volume. 

• SYSUT2 DD defines the output data set (NEWSET). The data set is written as 
the first or only data set on a 9-track tape volume. A density of 800 bits per 
inch is specified for the write operation. The output records are blocked to 
reduce the space required by the data set and to reduce the access time 
required when the data set is subsequently referred to. The data set is passed 
to a subsequent job step. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• GENERATE indicates that: (1) a maximum of three FIELD parameters is 
included in subsequent RECORD statements and (2) a maximum of 1 1 literal 
characters are included in subsequent FIELD parameters. 

• LABELS indicates that label records are included in the input stream. 

• The first RECORD statement controls the editing, as follows: (1) asterisks are 
placed in positions 1 through 10, (2) bytes 1 through 5 of the input record are 
converted from H-set BCD to EBCDIC mode and moved to positions 1 1 
through 15, and (3) an equal sign is placed in byte 16. 

• The second and third RECORD statements indicate that three 80-byte records 
(cards), to be written as user labels on the output data set, immediately 
follow. The first RECORD statement indicates that the following cards are to 
be treated as header labels. The second RECORD statement indicates that the 
following cards are to be treated as trailer labels. 
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IEBISAM Program 



IEBISAM is a data set utility used to copy an indexed sequential data set directly 
from one direct access volume to another. (See "Introduction" for general data 
set utility information.) 

Alternatively, IEBISAM can be used to reorganize an indexed sequential data set 
into a sequential (unloaded) data set and place that data set on a direct access or 
magnetic tape volume. The unloaded data set is in a form that can be 
subsequently loaded, that is, it can be converted back into an indexed sequential 
data set. 

Optionally, IEBISAM can be used to print the records of an indexed sequential 
data set. 

IEBISAM can be used to: 

• Copy an indexed sequential data set. 

• Create a sequential backup (transportable) copy of source data from an 
indexed sequential data set. 

• Create an indexed sequential data set from an unloaded data set. 

• Print an indexed sequential data set. 

At the completion or termination of IEBISAM, the highest return code 
encountered within the program is passed to the calling program. 

Copying an Indexed Sequential Data Set 

IEBISAM can be used to copy an indexed sequential data set directly from one 
direct access volume to another. When the data set is copied, the records marked 
for deletion are only deleted if the DELETE parameter was specified in the OPTCD 
(optional control program service) field. Those records that are contained in the 
overflow area of the original data set are moved into the primary area of the 
copied data set. The control information characteristics such as BLKSIZE and 
OPTCD can be overridden by new specifications. Caution should be used, 
however, when overriding these characteristics. 

Creating a Sequential Backup Copy 

An unloaded sequential data set can be created to serve as a backup or 
transportable copy of source data from an indexed sequential data set. Records 
marked for deletion within the indexed sequential data set are automatically 
deleted when the unloaded data set is created. When the data set is subsequently 
loaded — reconstructed into an indexed sequential data set — records that were 
contained in the overflow area assigned to the original data set are moved 
sequentially into the primary area. 

An unloaded data set consists of 80-byte logical records. The data set contains: 

• Fixed records from an indexed sequential data set. 

• Control information used in the subsequent loading of the data set. 

Control information consists of characteristics that were assigned to the indexed 
sequential data set. These characteristics are: 

• Optional control program service (OPTCD) 

• Record format (RECFM) 
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Logical record length (LRECL) 

Block size (BLKSIZE) 

Relative key position (RKP) 

Number of tracks in cylinder index (NTM) 

Key length (KEYLEN) 

Number of overflow tracks on each cylinder (CYLOFL) 

When a load operation is specified, these characteristics can be overridden by 
new specifications in the DCB parameter of the SYSUT2 DD statement (refer to 
"Job Control Statements" for a discussion of the SYSUT2 DD statement). Caution 
should be used, however, because checks are made to ensure that: 

1. Record format is the same as that of the original indexed sequential data set 
(either fixed (f) or variable (V) length). 

2. Logical record length is greater than or equal to that of the original indexed 
sequential data set when the RECFM is variable (v) or variable blocked (vb). 

3. For fixed records, the block size is equal to or a multiple of the logical record 
length of the records in the original indexed sequential data set. For variable 
records, the block size is equal to or greater than the logical record length plus 
four. 

4. Relative key position is equal to or less than the logical record length minus 
the key length. Following are relative key position considerations: 

• If the RECFM is V or VB, the relative key position should be at least 4. 

• If the DELETE parameter was specified in the OPTCD field and the RECFM is 
F or fixed blocked (FB), the relative key position should be at least 1. 

• If the DELETE parameter was specified in the OPTCD field and the RECFM is 
V or vb, the relative key position should be at least 5. 

5. The key length is less than or equal to 255 bytes. 

6. For a fixed unblocked data set with rkp=o, the LRECL value is the length of 
the data portion, not, as in all other cases, the data portion and key length. 
When changing the RECFM from fixed unblocked and RKP=0 to fixed blocked, 
the new LRECL must be equal to the old LRECL plus the old key length. 

If either RKP or KEYLEN is overridden, it might not be possible to reconstruct 
the data set. 

The number of 80-byte logical records in an unloaded data set can be determined 
by the formula: 

x = n( y+2) + 158 
78 

where x is the number of 80-byte logical records created, n is the number of 
records in the indexed sequential data set, and y is the length of a fixed record or 
the average length of variable records. 
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Figure 10-1 shows the format of an unloaded data set for the first three 
100-byte records of an indexed sequential data set. Each is preceded by two 
bytes (bb) that indicate the number of bytes in that record. (The last record is 
followed by two bytes containing binary zeros to identify the last logical record 
in the unloaded data set.) The characteristics of the indexed sequential data set 
are contained in the first two logical records of the unloaded data set. Data from 
the indexed sequential data set begins in the third logical record. Each logical 
record in the unloaded data set contains a binary sequence number (aa) in the 
first two bytes of the record. 





.80 bytes ■ 






a 


a 


b|b| 


Characteristics 






a 


a 




Characteristics 






a 


a 


b|b| 


76 bytes of data 






a 


a 




24 bytes of data |b|b| 


52 bytes of data 




a 
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48 bytes of data 


|b)b| 28 bytes of data 
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72 bytes of data 


|b|b| 





Figure 10-1. An Unloaded Data Set Created Using iebisam 

Creating an Indexed Sequential Data Set from an Unloaded Data Set 

An indexed sequential data set can be created from an unloaded version of an 
indexed sequential data set. When the unloaded data set is loaded, those records 
that were contained in the overflow area assigned to the original indexed 
sequential data set are moved sequentially into the primary area of the loaded 
indexed sequential data set. 

Printing the Logical Records of an Indexed Sequential Data Set 

The records of an indexed sequential data set can be printed or stored as a 
sequential data set for subsequent printing. Each input record is placed in a 
buffer from which it is printed or placed in a sequential data set. When the 
DELETE parameter is specified in the OPTCD field, each input record not marked 
for deletion is also placed in a buffer from which it is printed or placed in a 
sequential data set. Each printed record is converted to hexadecimal unless 
specified otherwise by the user. 

IEBISAM provides user exits so that the user can include his own routines to: 

• Modify records before printing. 

• Select records for printing or terminate the printing operation after a certain 
number of records have been printed. 

• Convert the format of a record to be printed. 

• Provide a record heading for each record if the record length is at least 18 
bytes. If no user routines are provided, each record is identified in sequential 
order on the printout. 

When a user routine is supplied for a print operation, IEBISAM issues a LOAD 
macro instruction. A BALR 14,15 instruction is used to give control to the user's 
routine. When the user's routine receives control, register contains a pointer to 
a record heading buffer; register 1 contains a pointer to an input record buffer. 

The input record buffer has a length equal to the length of the input logical 
record. 

Figure 10-2 shows the record heading buffer. 
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-Total length = line length of applicable printer - 
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Input record 



-Total length = input logical record length (LRECL)- 



Figure 10-2. Record Heading Buffer Used by iebisam 

The user returns control to IEBISAM by issuing a RETURN macro instruction (via 
register 14) or by using a BR 14 instruction after restoring registers 2 through 14. 
(Note that the user must save registers 2 through 14 when control is given to the 
user routine.) 

A user routine must place a return code in register 15 before returning control to 
IEBISAM. The possible return codes and their meanings are: 

• 00, which indicates that buffers are to be printed. 

• 04, which indicates that the buffers are to be printed and the operation is to 
be terminated. 

• 08, which indicates that this input record is not to be printed; processing 
continues. 

• 12, which indicates that this input record is not to be printed; terminate the 
operation. 



IEBISAM uses an input data set; the organization of the input data set depends on 
the operation to be performed, as follows: 

• If a data set is to be copied, unloaded, or printed in logical sequence, the input 
is an indexed sequential data set. 

• If a data set is to be loaded, the input is an unloaded sequential version of an 
indexed sequential data set. 

IEBISAM produces as output an output data set, which is the result of the 
IEBISAM operation, and a message data set, which contains informational 
messages and any error messages. 

IEBISAM provides a return code to indicate the results of program execution. The 
return codes and their meanings are: 

• 00, which indicates successful completion. 

• 04, which indicates that a return code of 04 or 12 was passed to IEBISAM by 
the user routine. 

• 08, which indicates that an error condition occurred that caused termination of 
the operation. 

• 12, which indicates that a return code other than 00, 04, 08, or 12 was passed 
to IEBISAM from a user routine. The job step is terminated. 
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Control 



16, which indicates that an error condition caused termination of the 
operation. 



IEBISAM is controlled by job control statements. No utility control statements are 
required. 



Job Control Statements 

Table 10-1 shows the job control statements necessary for using IEBISAM. 



Table 10-1. iebisam Job Control Statements 

Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (PGM=IEBISAM). Additional information is 

required on the exec statement to control the execution of IEBISAM; see 
"parm Information on the EXEC Statement" below. 

SYSUT1 DD Defines the input data set. 

SYSUT2 DD Defines the output data set. 

SYSPRINT DD Defines a sequential message data set, which can be written to a system output 
device, a tape volume, or a direct access device. 

If the block size of the SYSPRINT data set is not a multiple of 121, a default 
value of 121 is taken (no error message is issued, and no condition code is set). 



PARM Information on the EXEC Statement 



The PARM parameter on the EXEC statement is used to control the execution of 
IEBISAM. The PARM parameter is entered: 

PARM= {COPY } 

{ UNLOAD } 

{LOAD } 

{PRINTL } 

{'PRINTL[,N][,EXrr=routinename]'} 

The PARM values have the following meaning: 

• COPY specifies a copy operation. 

| • UNLOAD specifies an unload operation. This is the default. 

• LOAD specifies a load operation. 

• PRINTL specifies a print operation in which each record is converted to 
hexadecimal before printing. The N is an optional value that specifies that 
records are not to be converted to hexadecimal before printing. 

• EXIT is an optional value that specifies the name of an exit routine that is to 
receive control before each record is printed. 

Note: Exit routines must be included in either the job library or the link library. 

For a COPY operation, the SYSUT2 DD statement must include a primary space 
allocation that is sufficient to accommodate records that were contained in 
overflow areas in the original indexed sequential data set. New overflow areas 
can be specified when the data set is copied. 

For an UNLOAD operation, specifications that are implied by default or included 
in the DCB parameter of the SYSUT2 DD statement (for example, tape density) 
must be considered when the data set is subsequently loaded. If a block size is 
specified in the DCB parameter of the SYSUT2 DD statement, it must be a 
multiple of 80 bytes. 
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For a load operation, if the input data set resides on an unlabeled tape, the 
sysuti dd statement must specify a BLKSIZE that is a multiple of 80 bytes. 
Specifications that are implied by default or included in the DCB parameter of the 
SYSUTI DD statement must be consistent with specifications that were implied or 
included in the DCB parameter of the SYSUT2 DD statement used for the 
UNLOAD operation. The SYSUT2 DD statement must include a primary space 
allocation that is sufficient to accommodate records that were contained in 
overflow areas in the original indexed sequential data set. If new overflow areas 
are desired, they must be specified when the data set is loaded. 

For a printl operation, if the device defined by the SYSUT2 DD statement is a 
printer, the specified BLKSIZE must be equal to or less than the physical printer 
size; that is 121, 133, or 145 bytes. If BLKSIZE is not specified, 121 bytes is 
assumed. LRECL (or BLKSIZE when no LRECL was specified) must be between 
55 and 255 bytes. 

If a user routine is supplied for a PRINTL operation, IEBISAM issues a LOAD 
macro instruction to make the user routine available. A BALR 14,15 instruction is 
subsequently used to give control to the routine. When the user routine receives 
control, register contains a pointer to a record heading buffer, register 1 contains 
a pointer to an input record buffer. 



IEBISAM Examples 



The following examples illustrate some of the uses of IEBISAM. Table 10-2 can 
be used as a quick reference guide to IEBISAM examples. The numbers in the 
"Example" column point to the examples that follow. 



Table 10-2 


IEBISAM 


Example Directory 




Operation 


Data Set 
Organization 


Devices 


Comments 


Example 


COPY 


Indexed 
sequential 




2314 Disks 


Unblocked input; blocked output. 
Prime area and index separation. 


1 


UNLOAD 


Indexed- 

sequential, 

Sequential 




2314 Disk, 

9-track 

Tape 


Blocked output. 


2 


UNLOAD 


Indexed 

sequential, 

Sequential 




2314 Disk, 

7-track 

Tape 


Blocked output. Data set written 
as second data set on input 
volume. 


3 


LOAD 


Sequential, 

Indexed 

sequential 




9-track 
Tape, 
2314 Disk 


Input data set is second data set 
on tape volume. 


4 


PRINTL 


Indexed 

sequential, 

Sequential 




2314 Disk, 

System 

Printer 


Blocked input. Output not 
converted. 


5 
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IEBISAM Example 1 



IEBISAM Example 2 



In this example, an indexed sequential data set is to be copied from two 2314 
volumes. The output data is blocked. 

The example follows: 

//CPY JOB 09#770, SMITH 

// EXEC PGM=IEBISAM,PARM=COPY 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=ISAM01 ,VOLUME=SER=( 222222,333333 ), 

// DISP=( OLD, DELETE ),UNIT=( 2314,2 ) , DCB=( DSORG=IS , 

// LRECL=500 , BLKSIZE=500 , RECFM=F , RKP=4 ) 

//SYSUT2 DD DSNAME=ISAM02( INDEX ),UNIT=23 14, DISP=( NEW, 

// KEEP ) , VOLUME=SER=444444 , DCB=( DSORG=IS , BLKSIZE=1 000 , 

// RECFM=FB ) , SPACE=( CYL, ( 2 ) ) 

// DD DSNAME=ISAM02 ( PRIME ),UNIT=( 2314,2 ), 

// DCB=(DSORG=IS,BLKSIZE=1000,RECFM=FB),SPACE=(CYL, ( 10 ) ), 

// VOLUME=SER=( 444444,555555 ) ,DISP=( NEW, KEEP ) 

/* 

The control statements are discussed below: 

• EXEC specifies the program name and the COPY operation. 

• SYSUTl DD defines an indexed sequential input data set, which resides on two 
2314 volumes. 

• SYSUT2 DD defines the output data set index area; the index and prime areas 
are separated. 

• The second SYSUT2 DD defines the output data set prime area. Ten cylinders 
are allocated for the prime area on each of the two 2314 volumes. 



In this example, indexed sequential input is to be converted into a sequential data 
set; the output is to be placed on a 9-track tape volume. 

The example follows: 

//STEP1 JOB 09#770, SMITH 

// EXEC PGM=IEBISAM,PARM=UNLOAD 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=INDSEQ,UNIT=2314,DISP=( OLD, KEEP), 

// VOLUME=SER=1 11112 

//SYSUT2 DD DSNAME=UNLDSET,UNIT=2400,LABEL=( ,SL), 

// DISP=( , KEEP ),VOLUME=SER=001 234, DCB=(RECFM=FB, 

// LRECL=80,BLKSIZE=640 ) 

/* 

The control statements are discussed below: 

• EXEC specifies the program name and the UNLOAD operation. 

• SYSUTl DD defines the indexed sequential input data set, which resides on a 
2314 volume. 

• SYSUT2 DD defines the unloaded output data set. The data set consists of 
fixed blocked records, and is to reside as the first or only data set on a 9-track 
tape volume. The data set is to be written at a density of 800 bits per inch. 
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IEBISAM Example 3 



IEBISAM Example 4 



IEBISAM Example 5 



In this example, indexed sequential input is to be converted into a sequential data 
set and placed on a 7-track, tape volume. 

The example follows: 

//STEPA JOB 09#770, SMITH 

// EXEC PGM=IEBISAM,PARM=UNLOAD 

//SYSPRINT DD SYSOUT^A 

//SYSUT1 DD DSNAME=INDSEQ,UNIT=2314,DISP=(OLD,KEEP), 

// V0LUME=SER=1 11112 

//SYSUT2 DD DSNAME=UNLDSET,UNIT=2400-2,LABEL=(2 f SL), 

// VOLUME=SER=00 1234, DCB=( DEN=2 , RECFM=FB , LRECL=80 , 

// BLKSIZE=1040,TRTCH=C),DISP=( ,KEEP) 

/* 

The control statements are discussed below: 

• EXEC specifies the program name and the UNLOAD operation. 

• SYSUTl DD defines the input data set, which is an indexed sequential data set. 
The data set resides on a 2314 volume. 

• SYSUT2 DD defines the unloaded output data set. The data set consists of 
fixed blocked records, and is to reside as the second data set on a 7-track tape 
volume. The data set is to be written at a density of 800 bits per inch. 



In this example, an unloaded data set is to be converted to the form of the 
original indexed sequential data set. 

The example follows: 

//STEPA JOB 09#770, SMITH 

// EXEC PGM=IEBISAM,PARM=LOAD 

//SYSPRINT DD SYSOUT=A 

//SYSUTl DD DSNAME=UNLDSET,UNIT=2400,LABEL=( 2 , SL) , 

// DISP=( OLD , KEEP ) , VOLUME=SER=00 1 2 34 

//SYSUT2 DD DSNAME=INDSEQ,DISP=( ,KEEP ) ,DCB=( DSORG=IS ), 

// SPACE=(CYL,( 1 ) ) , VOLUME=SER= 1 1 1 1 12,UNIT=2314 

/* 

The control statements are discussed below: 

• EXEC specifies the program name and the LOAD operation. 

• SYSUTl DD defines the input data set, which is a sequential (unloaded) data 
set. The data set is the second data set on a 9-track tape volume. 

• SYSUT2 DD defines the output data set, which is an indexed sequential data 
set. One cylinder of space is allocated for the data set on a 2314 volume. 



In this example, the logical records of an indexed sequential data set are to be 
printed on a system output device. 

The example follows: 

//PRINT JOB 09#770, SMITH 

// EXEC PGM=IEBISAM,PARM-'PRINTL,N' 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=ISAM03,UNIT=2314,DISP=OLD, 

// VOLUME=SER=222222 

//SYSUT2 DD SYSOUT-A 

/* 
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The control statements are discussed below: 

• EXEC specifies the program name and the PRINTL operation. The output 
records are not to be converted to hexadecimal prior to printing. 

• SYSUTl DD defines the input data set, which resides on a 2314 volume. 

• SYSUT2 DD defines the output data set. A logical record length (LRECL) of 
121 bytes is assumed. 
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IEBPTPCH Program 



IEBPTPCH is a data set utility used to print or punch all, or selected portions, of a 
sequential or partitioned data set. Records can be printed or punched to meet 
either standard specifications or user specifications. (See "Introduction" for 
general data set utility information.) 

The standard specifications are: 

• Each logical record begins on a new printed line or punched card. 

• Each printed line consists of groups of 8 characters separated by 2 blanks. 
Each punched card contains up to 80 contiguous bytes of information. 

• Characters that cannot be printed appear as blanks. 

• When the input is blocked, each logical record is delimited by "*" and each 
block is delimited by "**". 

User formats can be specified, provided that no output record exceeds the 
capability of the output device. 

IEBPTPCH provides optional editing facilities and exits for user routines that can 
be used to process labels or manipulate input or output records. 

iebptpch can be used to: 

• Print or punch a sequential or partitioned data set in its entirety. 

• Print or punch selected members from a partitioned data set. 

• Print or punch selected records from a sequential or partitioned data set. 

• Print or punch the directory of a partitioned data set. 

• Print or punch an edited version of a sequential or partitioned data set. 

At the completion or termination of the program, the highest return code 
encountered within the program is passed to the calling program. 

Printing or Punching a Data Set 

IEBPTPCH can be used to print or punch a sequential data set or a partitioned 
data set in its entirety. Data to be printed or punched can be either hexadecimal 
or a character representation of valid alphameric bit configurations. For a print 
operation, packed decimal data should be converted to unpacked decimal or 
hexadecimal mode to ensure that all characters are printable. 

For a standard print operation, each logical record is printed in groups of eight 
characters. Each set of eight characters is separated from the next by two blanks. 
Up to 96 data characters can be included on a printed line. (An edited output 
can be produced to omit the blank delimiters and print up to 144 characters per 
line.) 

Data from an input logical record is punched in contiguous columns in the 
punched card(s) representing that record. Sequence numbers can be created and 
placed in columns 73 through 80 of the punched cards. 

Printing or Punching Selected Members 

IEBPTPCH can be used to print or punch selected members of a partitioned data 
set. Utility control statements are used to specify members to be printed or 
punched. 
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Printing or Punching Selected Records 

IEBPTPCH can be used to print selected records from a sequential or partitioned 
data set. Utility control statements can be used to specify: 

• The termination of a print or punch operation after a specified number of 
records has been printed or punched. 

• The printing or punching of every nth record. 

• The starting of a print or punch operation after a specified number of records. 

Printing or Punching a Partitioned Directory 

IEBPTPCH can be used to print or punch the contents of a partitioned directory. 
Each directory block is printed in groups of eight characters. If the directory is 
printed in hexadecimal representation, the first four printed characters of each 
directory block indicate the total number of used bytes in that block. For details 
of the format of the directory, see 0S/VS1 System Data Areas, SY28-0605, or 
0S/VS2 System Data Areas, SY28-0606. 



Data from a directory block is punched in contiguous columns in the punched 
cards renresentine that block. 



cards representing that block. 



Printing or Punching an Edited Data Set 

IEBPTPCH can be used to print or punch an edited version of a sequential or a 
partitioned data set. Utility control statements can be used to specify editing 
information that applies to a record, a group of records, selected groups of 
records, or an entire member or data set. 

An edited data set is produced by: 

• Rearranging or omitting defined data fields within a record. 



Input and Output 



Converting data from packed decimal to unpacked decimal or from alphameric 
to hexadecimal representation. 



IEBPTPCH uses the following input: 

• An input data set, which contains the data that is to be printed or punched. 
The input data set can be either sequential or partitioned. 

• A control data set, which contains utility control statements. The control data 
set is required for each use of IEBPTPCH. 

IEBPTPCH produces the following output: 

• An output data set, which is the printed or punched data set. 

• A message data set, which contains informational messages (for example, the 
contents of the control statements) and any error messages. 

IEBPTPCH provides a return code to indicate the results of program execution. 
The return codes and their meanings are: 

• 00, which indicates successful completion. 

• 04, which indicates that either a physical sequential data set is empty or a 
partitioned data set has no members. 

• 08, which indicates that a member specified for printing does not exist in the 
input data set. Processing continues with the next member. 

• 12, which indicates that an unrecoverable error occurred or that a user routine 
passed a return code of 12 to IEBPTPCH. The job step is terminated. 
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16, which indicates that a user routine passed a return code of 16 to 
iebptpch. The job step is terminated. 



Control 



IEBPTPCH is controlled by job control statements and utility control statements. 
The job control statements are required to execute or invoke the IEBPTPCH 
program and to define the data sets that are used and produced by the program. 
The utility control statements are used to control the functions of IEBPTPCH. 

Job Control Statements 

Table 11-1 shows the job control statements necessary for using IEBPTPCH. 

Table 11-1. iebptpch Job Control Statements 

Statement Use 

JOB Initiates the job step. 

EXEC Specifies the program name (PGM=IEBPTPCH) or, if the job control 

statements reside in a procedure library, the procedure name. 

SYSPRINT DD Defines a sequential message data set. The data set can be written to a 
system output device, a tape volume, or a direct access device. 

SYSUT1 DD Defines a sequential or partitioned input data set. 

SYSUT2 DD Defines the output (printed or punched) data set. 

SYSIN DD Defines the control data set. The control data set normally resides in the 

input stream; however, it can be defined as a member in a partitioned data 
set. 

The input data set can contain fixed, variable, undefined, or variable spanned 
records. 

Both the output data set and the message data set can be written to the system 
output device if it is a printer. Variable spanned records are allowed only when 
the input is sequential. 

If the logical record length of the input records is such that the output would 
exceed the output record length, the utility divides the record into multiple lines 
or cards in the case of standard printed output, standard punched output, or 
when the PREFORM operand was specified. Otherwise, only part of the input 
record is printed (a maximum of 144 characters) or punched (a maximum of 80 
characters). 



Restrictions 



The SYSPRINT DD statement is required for each use of IEBPTPCH. The 
RECFM is always FBA, the LRECL is always 121. Output can be blocked by 
specifying a block size that is a multiple of 121 on the SYSPRINT DD 
statement. The default block size is 121. 

The SYSUTi DD statement is required for each use of IEBPTPCH. The RECFM 
except for undefined records), BLKSIZE, and LRECL (except for undefined and 
fixed unblocked records) must be present on the DD statement, in the dscb, 
or on the tape label. 

The SYSUT2 DD statement is required every time IEBPTPCH is used. The 
RECFM is always FBA or FBM. The LRECL parameter, or, if no logical record 
length is specified, the BLKSIZE parameter, specifies the number of characters 
to be written per printed line or per punched card (this count includes a 
control character). The number of characters specified must be in the range of 
2 through 145. The default values for edited output lines are 121 characters 
per printed line and 81 characters per punched card. The SYSUT2 data set can 
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be blocked by specifying both the LRECL and the BLKSIZE parameters, in 
which case, block size must be a multiple of logical record length. 

• The SYSIN DD statement is required for each use of IEBPTPCH. The RECFM is 
always FB, the LRECL is always 80. Any blocking factor that is a multiple of 
80 can be specified for the BLKSIZE. The default block size is 80. 

• A partitioned directory to be printed or punched must be defined as a 
sequential data set (TYPORG=PS). You must specify RECFM ==U, BLKSIZE=256, 
and LRECL=256 on the SYSUTl DD statement. 

Utility Control Statements 

IEBPTPCH is controlled by utility control statements. The control statements are 
shown in the order in which they must appear, as follows: 

• PRINT or PUNCH statement, which specifies that the data is to be either 
printed or punched. 

• TITLE statement, which specifies that a title is to precede the printed or 
punched data. 

• EXITS statement, which specifies that user routines are provided. 

• MEMBER statement, which specifies that the input is a partitioned data set and 
that a selected member is to be printed or punched. 

• RECORD statement, which specifies whether editing is to be performed, that is, 
records are to be printed or punched to nonstandard specifications. 

• LABELS statement, which specifies whether user labels are to be treated as 
data. 

The control statements are included in the control data set, as required. Any 
number of MEMBER and RECORD statements can- be included in a job step. 



PRINT Statement 



The PRINT statement is used to initiate the IEBPTPCH operation. If this is a print 
operation, PRINT must be the first statement in the control data set. 

The format of the PRINT statement is: 

[label] PRINT [PREFORM= {A } 

{M}] 

[,TYPORG= {PS } 

{PO}] 
[,TOTCONV= {XE } 
{PZ }] 

[,CNTRL=n] 

[,STRTAFT=n] 

[,STOPAFT=n] 

[,SKIP=n] 

[,MAXNAME=n] 

[,MAXFLDS=n] 

[,MAXGPS=n] 

[,MAXLITS=n] 

[,INITPG=n] 

[,MAXLINE=n] 
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where: 

PREFORM= 

specifies that a control character is provided as the first character of each 
record to be printed. The control characters are used to control the spacing, 
number of lines per page, and page ejection. If an error occurs, the print 
operation is terminated. If PREFORM is coded, except for syntax checking, any 
additional PRINT operands and all other control statements except LABELS 
statements are ignored. PREFORM must not be used for printing data sets with 
vs or VBS records longer than 32K bytes. These values can be coded: 

A 

specifies that an ASA control character is provided as the first character of 
each record to be printed. If the input record length exceeds the output 
record length, the utility uses the ASA character for printing the first line, 
with a single space character on all subsequent lines of the record. 

M 

specifies that a machine-code control character is provided as the first 
character of each record to be, printed. If the input record length exceeds 
the output record length, the utility prints all lines of the record with a 
print-skip-one-line character until the last line of the record, which will 
contain the actual character provided as input. 

TYPORG= 

specifies the organization of the input data set. If TYPORG is omitted, 
sequential organization is assumed. These values can be coded: 

PS 

specifies that the input data set is organized sequentially. 

PO 

specifies that the input data set is partitioned. 

TOTCONV= 

specifies the representation of data to be printed. TOTCONV can be overridden 
by any user specifications (RECORD statements) that pertain to the same data. 
These values can be coded: 

XE 

specifies that data is to be printed in 2-character-per-byte hexadecimal 
representation (for example, C3 40 F4 F6). If XE is not specified, data is 
printed in 1 -character per byte alphameric representation. The above 
example would appear as C 46. 

PZ 

specifies that data (packed decimal mode) is to be converted to unpacked 
decimal mode. If TOTCONV is omitted, data is not converted. IEBPTPCH does 
not check for packed decimal mode. The output is unpredictable when the 
input is other than packed decimal. 

CNTRL=n 

specifies a control character for the output device that indicates line spacing, 
as follows: 1 indicates single spacing; 2 indicates double spacing; and 3 
indicates triple spacing. If CNTRL is omitted, 1 is assumed. 
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PUNCH Statement 



STRTAFT=n 

specifies, for sequential data sets, the number of logical records (physical 
blocks in the case of vs or VBS type records longer than 32K bytes) to be 
skipped before printing begins. For partitioned data sets, STRTAFT=n specifies 
the number of logical records to be skipped in each member before printing 
begins. The n value must not exceed 32,767. If STRTAFT is specified and 
RECORD statements are present, the first RECORD statement of a member 
describes the format of the first logical record to be printed. 

STOPAFT=n 

specifies, for sequential data sets, the number of logical records (or physical 
blocks in the case of VS or VBS records longer than 32K bytes) to be printed. 
For partitioned data sets, this specifies the number of logical records to be 
printed in each member to be processed. The n value must not exceed 32,767. 
If STOPAFT is specified and RECORD statements are present, the operation is 
terminated when the STOPAFT count is satisfied, at the end of a record group, 
or at the end of the data set, whichever occurs first. 

SKIP=n 

specifies that every nth record (or physical block in the case of vs or VBS 
records longer than 32K bytes) is to be printed. If SKIP is omitted, successive 
logical records are printed. 

MAXNAME=n 

specifies a number no less than the total number of subsequent MEMBER 
statements. If MAXNAME is omitted when there is a MEMBER statement 
present, the print request is terminated. 

MAXFLDS=n 

specifies a number no less than the total number of FIELD parameters 
appearing in subsequent RECORD statements. If MAXFLDS is omitted when 
there is a FIELD parameter present, the print request is terminated. 

MAXGPS=n 

specifies a number no less than the total number of IDENT parameters 
appearing in subsequent RECORD statements. If MAXGPS is omitted when there 
is an IDENT parameter present, the print request is terminated. 

MAXLITS=n 

specifies a number no less than the total number of characters contained in 
the IDENT literals of subsequent RECORD statements. If MAXLITS is omitted 
when there is a literal present, the print request is terminated. 

INITPG=n 

specifies the initial page number; the pages are numbered sequentially 
thereafter. If INITPG is omitted, 1 is assumed. The INITPG parameter must not 
exceed a value of 9999. 

MAXLINE==n 

specifies the maximum number of lines to a printed page. Spaces, titles, and 
subtitles are included in this number. If MAXLINE is omitted, 60 is assumed. 



The PUNCH statement is used to initiate the IEBPTPCH operation. If this is a 
punch operation, PUNCH must be the first statement in the control data set. 
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The format of the PUNCH statement is: 

[label] PUNCH [PREFORM= {A} 

{M}] 

[,TYPORG={PS} 

{PO}] 

[,TOTCONV= {XE} 
{PZ}] 
[,CNTRL=n] 
[,STRTAFT=n] 
[,STOPAFT=n] 
[,SKIP=n] 
[,MAXNAME=n] 
[,MAXFLDS=n] 
[,MAXGPS=n] 
[,MAXLITS=n] 
[,CDSEQ=n] 
[,CDINCR=n] 

where: 

PREFORM= 

specifies that a control character is provided as the first character of each 
record to be punched. The control characters are used to select a stacker. If 
an error is discovered, the punch operation is terminated. If PREFORM is 
coded, except for syntax checking, any additional PUNCH operands and all 
other control statements except LABELS statements are ignored. PREFORM 
must not be used for punching data sets with VS or VBS records longer than 
32K bytes. These values can be coded: 

A 

specifies that an ASA control character is provided as the first character of 
each record to be punched. If the input record length exceeds the output 
record length, the utility duplicates the ASA character on each output card 
of the record. 

M 

specifies that a machine-code control character is provided as the first 
character of each record to be punched. If the input record length exceeds 
the output record length, the utility duplicates the machine control character 
on each output card of the record. 

TYPORG= 

specifies the organization of the input data set. If TYPORG is omitted, 
sequential organization is assumed. These values can be coded: 

PS 

specifies that the input data set is organized sequentially. 

PO 

specifies that the input data set is partitioned. 
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TOTCONV= 

specifies the representation of data to be punched. TOTCONV can be 
overridden by any user specifications (RECORD statements) that pertain to the 
same data. These values can be coded: 

XE 

specifies that data is to be punched in 2-character-per-byte hexadecimal 
representation (for example, C3 40 F4 F6). If XE is not specified, data is 
punched in 1 -character per byte alphameric representation. The above 
example would appear as C 46. 

PZ 

specifies that data (packed decimal mode) is to be converted to unpacked 
decimal mode. If TOTCONV is omitted, data is not converted. IEBPTPCH 
does not check for packed decimal mode. The output is unpredictable when 
the input is other than packed decimal. 

CNTRL=n 

specifies a control character for the output device that is used to select the 
stacker, as follows: 1 indicates the first stacker and 2 indicates the second 
stacker. If CNTRL is omitted, 1 is assumed. 

STRTAFT=n 

specifies, for sequential data sets, the number of logical records (physical 
blocks in the case of VS or VBS type records longer than 32K bytes) to be 
skipped before punching begins. For partitioned data sets, STRTAFT=n specifies 
the number of logical records (physical blocks in the case of VS or VBS type 
records longer than 32K bytes) to be skipped in each member before punching 
begins. The n value must not exceed 32,767. If STRTAFT is specified and 
RECORD statements are present, the first RECORD statement of a member 
describes the format of the first logical record to be punched. 

STOPAFT==n 

specifies, for sequential data sets, the number of logical records (or physical 
blocks in the case of VS or VBS records longer than 32K bytes) to be punched. 
For partitioned data sets, this specifies the number of logical records (or 
physical blocks in the case of VS or VBS records longer than 32K bytes) to be 
punched in each member to be processed. The n value must not exceed 
32,767. If STOPAFT is specified and RECORD statements are present, the 
operation is terminated when the STOPAFT count is satisfied or at the end of 
the first record group, whichever occurs first. 

SKIP=n 

specifies that every nth record (or physical block in the case of VS or VBS 
records longer than 32K bytes) is to be punched. If SKIP is omitted, successive 
logical records are punched. 

MAXNAME=n 

specifies a number no less than the total number of subsequent MEMBER 
statements. If MAXNAME is omitted when there is a MEMBER statement 
present, the punch request is terminated. 

MAXFLDS=n 

specifies a number no less than the total number of FIELD parameters 
appearing in subsequent RECORD statements. If MAXFLDS is omitted when 
there is a FIELD parameter present, the punch request is terminated. 

MAXGPS=n 

specifies a number no less than the total number of IDENT parameters 
appearing in subsequent RECORD statements. If MAXGPS is omitted when there 
is an IDENT parameter present, the punch request is terminated. 
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TITLE Statement 



EXITS Statement 



MAXLITS=n 

specifies a number no less than the total number of characters contained in 
the IDENT literals of subsequent RECORD statements. If MAXLITS is omitted 
when there is a literal present, the punch request is terminated. 

CDSEQ=n 

specifies the initial sequence number of a deck of punched cards. This value 
must be contained in columns 73 through 80. Sequence numbering is 
initialized for each member of a partitioned data set. If CDSEQ is omitted, the 
cards are not numbered. If the value of n is zero, 00000000 is assumed as a 
starting sequence number. 

CDINCR=n 

specifies the increment to be used in generating sequence numbers. If CDINCR 
is omitted and CDSEQ is coded, 10 is assumed as an increment value for 
sequence numbering. 



The TITLE statement is used to request title and subtitle records. Two TITLE 
statements can be included for each use of IEBPTPCH. A first TITLE statement 
defines the title, and a second defines the subtitle. The TITLE statement, if 
included, must immediately follow the PRINT or PUNCH statement in the control 
data set. 

The format of the TITLE statement is: 

[name] TITLE ITEM=('t/t/e , [,output-/ocat/on])[,ITEM...] 

where: 

ITEM= 

specifies title or subtitle information. The values that can be coded are: 

'title' 

specifies the title or subtitle literal (maximum length of 40 bytes), enclosed 
in apostrophes. If the literal contains apostrophes, each apostrophe must be 
written as two consecutive apostrophes. 

output-location 

specifies the starting position at which the literal for this item is to be 
placed in the output record. If output-location is not specified, 1 is assumed. 
The specified title may not exceed the output logical record length minus 1. 



The EXITS statement is used to identify exit routines supplied by the user. Exits 
to label processing routines are ignored if the input data set is partitioned. 
Linkage to and from user routines are discussed in "Appendix A: Exit Routine 
Linkage." 

The EXITS statement, if included, must immediately follow any title statement 
or follow the PRINT or PUNCH statement. 

The format of the EXITS statement is: 

[label] EXITS [INHDR= routinename] 
[,INTLR= routinename] 
[,INREC = routinename] 
[,OUTREC=rouf/nename] 
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MEMBER Statement 



RECORD Statement 



where: 

INHDR = routinename 

specifies the symbolic name of a routine that processes user input header 
labels. 

INTLR = routinename 

specifies the symbolic name of a routine that processes user input trailer 
labels. 

INREC = routinename 

specifies the symbolic name of a routine that manipulates each logical record 
(or physical block in the case of VS or VBS records longer than 32K bytes) 
before it is processed. 

OUTREC = routinename 

specifies the symbolic name of a routine that manipulates each logical record 
(or physical block in the case of VS or VBS records longer than 32K bytes) 
before it is printed or punched. When standard specifications are used, this 
exit is not available. 



The MEMBER statement is used to identify members to be printed or punched. 
All RECORD statements that follow a MEMBER statement pertain to the member 
indicated in that MEMBER statement only. When RECORD and MEMBER 
statements are used, at least one MEMBER statement must precede the first 
RECORD statement. If no RECORD statement is used, the member is processed to 
standard specifications. 

If no MEMBER statement appears, and a partitioned data set is being processed, 
all members of the data set are printed or punched. Any number of MEMBER 
statements can be included in a job step. 

The format of the MEMBER statement is: 

[label] MEMBER NAME= [membemame } 

{aliasname } 

where: 

NAME= 

specifies a member to be printed or punched. These values can be coded: 

membemame 

specifies a member by its member name. 

aliasname 

specifies a member by its alias. 

If the NAME parameter is specified in the MEMBER statement, MAXNAME 
must be specified in a PRINT or PUNCH statement. 



The RECORD statement is used to define a group of records, called a record 
group, that is to be printed or punched to the user's specifications. A record 
group consists of any number of records to be edited identically. 

If no RECORD statements appear, the entire data set, or named member, is 
printed or punched to standard specifications. If a RECORD statement is used, all 
data following the record group it defines (within a partitioned member or within 
an entire sequential data set) must be defined with other RECORD statements. 
Any number of RECORD statements can be included in a job step. 
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The format of the RECORD statement is: 

[label] RECORD [IDENT= (lengthSname%input-location)] 

[FIELD= (length[,input-location][,conversion] 
[,ouiput-/ocat/on])[,FIELD=...] 

where: 

IDENT= 

identifies the last record of the record group to which the FIELD parameters 
apply. If IDENT is omitted and STOPAFT is not included with the PRINT or 
PUNCH statement, record processing halts after the last record in the data set. 
If IDENT is omitted and STOPAFT is included with the print or punch 
statement, record processing halts when the STOPAFT count is satisfied or after 
the last record of the data set is processed, whichever occurs first. The values 
that can be coded are: 

length 

specifies the length (in bytes) of the field that contains the identifying name 
in the input records. The length cannot exceed eight bytes. 

'name' 

specifies the exact literal that identifies the last record of a record group. If 
the literal contains apostrophes, each must be written as two consecutive 
apostrophes. 

input-location 

specifies the starting location of the field that contains the identifying name 
in the input records. 

Note: The sum of the length and the input location must be equal to or less 
than the input LRECL plus one. 

FIELD= 

specifies field-processing and editing information. These values can be coded: 

length 

specifies the length (in bytes) of the input field to be processed. 

Note: The length must be equal to or less than the initial input LRECL. 

input-location 

specifies the starting byte of the input field to be processed. If input-location 
is not specified, 1 is assumed. 

Note: The sum of the length and the input location must be equal to or less 
than the input LRECL plus one. 

conversion 

specifies a two-byte code that indicates the type of conversion to be 
performed on this field before it is printed or punched. If conversion is not 
specified, the field is moved to the output area without change. The values 
that can be coded are: 

PZ 

specifies that data (packed decimal) is to be converted. to unpacked 
decimal data. The converted portion of the input record (length L) 
occupies 2L - 1 output characters. 

XE 

specifies that data (alphameric) is to be converted to hexadecimal data. 
The converted portion of the input record (length L) occupies 2L output 
characters. 
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LABELS Statement 



output-location 

specifies the starting location of this field in the output records. If 
output -location is not specified, 1 is assumed. Unspecified fields in the 
output records appear as blanks in the printed or punched output. Data that 
exceeds the SYSUT2 printer or punch size is not printed or punched. The 
specified fields may not exceed the logical output record length minus 1. 
When specifying one or more fields, the sum of all lengths and all extra 
characters needed for conversions must be equal to or less than the output 
LRECL minus one. 

A RECORD statement referring to a partitioned data set for which no members 
have been named need contain only FIELD parameters. These are applied to the 
records in all members of the data set. 

If a FIELD parameter is included in the RECORD statement, MAXFLDS must be 
specified in the PRINT or PUNCH statement. 

If an IDENT parameter is included in the RECORD statement, MAXGPS must be 
specified in the PRINT or PUNCH statement. If a literal is specified in the IDENT 
parameter, MAXLITS must be specified in the PRINT or PUNCH statement. 



The LABELS statement specifies whether user labels are to be treated as data. 
For a detailed discussion of this option, refer to "Processing User Labels as 
Data," in "Appendix D: Processing User Labels." 

The format of the LABELS statement is: 

[name] LABELS [DATA= { YES } 

{NO} 
{ALL} 
{ONLY}] 

where: 

DATA= 

specifies whether user labels are to be treated as data. The values that can be 
coded are: 

YES 

specifies that any user labels that are not rejected by a user's label 
processing routine are to be treated as data. Processing of labels as data 
stops in compliance with standard return codes. If no value is entered, YES 
is assumed. 



NO 



specifies that user labels are not to be treated as data. 

ALL 

specifies that user labels are to be treated as data regardless of any return 
code. A return code of 16 causes the utility to complete the processing of 
the remainder of the group of user labels and to terminate the job step. 

ONLY 

specifies that only user header labels are to be treated as data. User header 
labels are processed as data regardless of any return code. The job 
terminates upon return from .the OPEN routine. 

Note: LABELS DATA=NO must be specified to make standard user label (SUL) 
exits inactive when an input data set with nonstandard labels (NSL) is to be 
processed. 
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IEBPTPCH Examples 



IEBPTPCH Example 1 



If more than one valid labels statement is included, all but the last LABELS 
statement are ignored. 



The following examples illustrate some of the uses of IEBPTPCH. Table 11-2 can 
be used as a quick reference guide to IEBPTPCH examples. The numbers in the 
"Example" column point to the examples that follow. 



Table 11-2. iebptpch 


Example Directory 




Operation 


Data Set 
Organization 


Devices 


Comments 


Example 


PRINT 


Sequential 


9-track Tape, 
System Printer 


Standard format. Conversion to 
hexadecimal. 


1 


PUNCH 


Sequential 


7-track Tape, 
Card Reader 


Standard format. Conversion to 
hexadecimal. 


2 


PRINT 


Partitioned 


3330 Drum, 
System Printer 


Standard format. Conversion to 
hexadecimal. Ten records from 
each member are to be printed. 


3 


PRINT 


Partitioned 


2314 Disk, 
System Printer 


Standard format. Conversion to 
hexadecimal. Two members are 
to be printed. 


4 


PRINT 


Sequential 


9-track Tape, 
System Printer 


User-specified format. Input 
data set is the second data set 
on the volume. 


5 


PUNCH 


Sequential 


2314 Disk, 
Card Reader 
Punch 


User-specified format. Sequence 
numbers are to be assigned and 
punched. 


6 


PRINT 


Sequential, 
Partitioned 


2314 Disk, 
System Printer 


Standard format. Conversion to 
hexadecimal. 


7 


PUNCH 


Sequential 


Card Reader, 
Card Read 
Punch 


Standard format. Control data 
set is a member in a cataloged 
partitioned data set. 


8 


PRINT 


Sequential 


2314 Disk, 
System Printer 


User-specified format. User 
routines are provided. Processing 
ends after first record group is 
printed. 


9 



In this example, a sequential data set is to be printed according to standard 
specifications. The input data set resides on a 9-track tape volume, originally 
written at a density of 800 bits per inch. The printed output is to be converted to 
hexadecimal. 

The example follows: 

//PRINT JOB 09#660, SMITH 

// EXEC PGM=IEBPTPCH 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD UNIT=2400,LABEL=( ,NL ) , VOLUME=SER=001 234 , 

// DISP=( OLD, KEEP ) ,DCB=( RECFM=U, BLKSIZE=2000 ) 

//SYSUT2 DD SYSOUT=A 

//SYSIN DD * 

PRINT TOTCONV=XE 

TITLE ITEM=( 'PRINT SEQ DATA SET WITH CONV TO HEX ' , 1 ) 
/* 

The control statements are discussed below. 

• sysuti DD defines the input data set. The data set contains undefined 
records; no record is larger than 2,000 bytes. 



IEBPTPCH Program 11-13 



IEBPTPCH Example 2 



IEBPTPCH Example 3 



SYSUT2 DD defines the output data set. The data set is written to the system 
output device (printer assumed). Each printed line contains groups (8 
characters each) of hexadecimal information. Each record begins a new line of 
printed output. 

SYSIN DD defines the control data set, which follows in the input stream. The 
control data set contains the PRINT and TITLE statements. 

PRINT initiates the print operation and specifies conversion from alphameric to 
hexadecimal representation. 

TITLE specifies a title to be placed beginning in column 10 of the printed 
output. The title is not converted to hexadecimal. 



In this example, a sequential data set is to be punched according to standard 
specifications. The input data set resides on a 7-track tape volume, originally 
written at a density of 556 bits per inch. The punched output is converted to 
hexadecimal. 

The example follows: 

//PUNCHSET JOB 09#660, SMITH 

// EXEC PGM-IEBPTPCH 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=INSET,UNIT=2400,VOLUME=SER=001234, 

// LABEL=( , NL),DISP=( OLD, KEEP ), DCB=( DEN= 1 ,RECFM=FB, 

// LRECL=80 , BLKSIZE=2000 , TRTCH=C ) 

//SYSUT2 DD UNIT=2540-2 

//SYSIN DD * 

PUNCH TOTCONV=XE 

TITLE ITEM=( 'PUNCH SEQ DATA SET WITH CONV TO HEX ' , 1 ) 
/* 

The control statements are discussed below: 

• SYSUTl DD defines the input data set. The data set contains 80-byte, fixed 
blocked records. 

• SYSUT2 DD defines the output data set. The data set is to be punched by an 
IBM 2540-2 Card Read Punch (punch feed). Each record from the input data 
set is represented by two punched cards. 

• SYSIN DD defines the control data set, which follows in the input stream. The 
control data set contains the PUNCH and TITLE statements. 

• PUNCH initiates the punch operation and specifies conversion from alphameric 
to hexadecimal representation. 

• TITLE specifies a title to be placed beginning in column 10. The title is not 
converted to hexadecimal. 



In this example, a partitioned data set (ten records from each member) is to be 
printed according to standard specifications. The input data set resides on a 3330 
volume. The printed output is converted to hexadecimal. 
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IEBPTPCH Example 4 



The example follows: 

//PRINTPDS JOB 09#660, SMITH 

// EXEC PGM=IEBPTPCH 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=PDS,UNIT=3330,DISP=( OLD, KEEP), 

// VOLUME=SER=1 1 1 1 1 2 ,DCB=( RECFM=U, BLKSIZE=3625 ) 

//SYSUT2 DD SYSOUT=A 

//sysiN DD * 

PRINT TOTCONV=XE , TYPORG=PO , STOPAFT= 1 
TITLE ITEM=( 'PRINT PDS - 10 RECS EACH MEM ',20) 
/* 

The control statements are discussed below: 

• SYSUTl DD defines the input data set. The data set contains undefined 
records; no record is larger than 3,625 bytes. 

• SYSUT2 DD defines the output data set on the system output device (printer 
assumed). Each printed line contains groups (8 characters each) of 
hexadecimal information. Each record begins a new line of printed output. The 
size of the record determines how many lines of printed output are required 
per record. 

• SYSIN DD defines the control data set, which follows in the input stream. The 
control data set contains the PRINT and TITLE statements. 

• PRINT initiates the print operation, specifies conversion from alphameric to 
hexadecimal representation, indicates that the input data set is partitioned, and 
specifies that ten records from each member are to be printed. 

• TITLE specifies a title to be placed beginning in column 20 of the printed 
output. The title is not converted to hexadecimal. 



In this example, two partitioned members are to be printed according to standard 
specifications. The input data set resides on a 2314 volume. The printed output is 
to be converted to hexadecimal. 

The example follows: 

//PRNTMEMS JOB 09 #660, SMITH 

// EXEC PGM=IEBPTPCH 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=PDS,DISP= (OLD, KEEP ),VOLUME=SER=1 1 1 1 12, 

// DCB=(RECFM=F,LRECL=80,BLKSIZE=80 ),UNIT=2314 

//SYSUT2 DD SYSOUT=A 

//SYSIN DD * 

PRINT TYPORG=PO , TOTCONV=XE , MAXNAME=2 

TITLE ITEM=( 'PRINT TWO MEMBS WITH CONV TO HEX ',10) 

MEMBER NAME=MEMBER1 

MEMBER NAME=MEMBER2 
/* 

The control statements are discussed below: 

• SYSUTl DD defines the input data set. The data set contains 80-byte, fixed 
records. 

• SYSUT2 DD defines the output data set on the system output device (printer 
assumed). Each printed line contains groups (8 characters each) of 
hexadecimal information. Each record begins a new line of printed output. 

• SYSIN DD defines the control data set, which follows in the input stream. The 
control data set contains PRINT, TITLE, and MEMBER statements. 
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IEBPTPCH Example 6 



PRINT initiates the print operation, indicates that the input data set is 
partitioned, specifies conversion from alphameric to hexadecimal 
representation, and indicates that two MEMBER statements appear in the 
control data set. 

TITLE specifies a title to be placed beginning in column 10 of the printed 
output. The title is not converted to hexadecimal. 

MEMBER specifies the member names of the members to be printed. 



In this example, a sequential data set is to be printed according to user 
specifications. The input data set is the second data set on a 9-track tape volume. 
The data set was originally written at a density of 800 bits per inch. 

The example follows: 

//PTNONSTD JOB 09#660, SMITH 
// EXEC PGM=IEBPTPCH 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=SEQSET,UNIT=2400,LABEL=( 2 , SUL ) , 
// DISP=( OLD , KEEP ) , VOLUME=SER=00 1234, DCB=( RECFM=FB , 
// LRECL=80,BLKSIZE=2000 ) 
//SYSUT2 DD SYSOUT=A 
* 

MAXFLDS-1 

INHDR=HDRIN, INTLR=TRLIN 

FIELD=( 80 ) 

DATA=YES 



//SYSIN DD 

PRINT 

EXITS 

RECORD 

LABELS 

/* 



The control statements are discussed below: 

• SYSUT1 DD defines the input data set. The data set contains 80-byte, fixed 
blocked records. 

• SYSUT2 DD defines the output data set on the system output device (printer 
assumed). Each printed line contains 80 contiguous characters (one record) of 
information. 

• SYSIN DD defines the control data set, which follows in the input stream. The 
control data set contains the PRINT, RECORD, EXITS, and LABELS statements. 

• PRINT initiates the print operation and indicates that one FIELD parameter is 
included in a subsequent RECORD statement. 

• RECORD indicates that each input record is to be processed in its entirety (80 
bytes). Each input record is printed in columns 1 through 80 on the printer. 

• LABELS specifies that user header and trailer labels are to be printed according 
to the return code issued by the user exits. 

• exits indicates that exits will be taken to user header-label and trailer-label 
processing routines when these labels are encountered on the SYSUTl data set. 



In this example, a sequential data set is to be punched according to user 
specifications. The input data set resides on a 2314 volume. 
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The example follows: 

//PHSEQNO JOB 09#660, SMITH 

// EXEC PGM=IEBPTPCH 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=SEQSET,UNIT=2314,LABEL=( , SUL ) , 

// VOLUME=SER=1 1 1 1 1 2 ,DISP=( OLD, KEEP ) ,DCB=( RECFM=FB, 

// LRECL=80,BLKSIZE=2000 ) 

//SYSUT2 DD DSNAME=PUNCHSET,UNIT=2540-2 

//SYSIN DD * 

PUNCH MAXFLDS=1 , CDSEQ=00000000 , CDINCR=20 

RECORD FIELD=( 72 ) 

LABELS DATA-YES 
/* 

The control statements are discussed below: 

• SYSUTl DD defines the input data set. The data set contains 80-byte, fixed 
blocked records. 

• SYSUT2 DD defines the output data set. The data set is to be punched by an 
IBM 2540-2 Card Read Punch (punch feed). Each record from the input data 
set is represented by one punched card. 

• SYSIN DD defines the control data set, which follows in the input stream. The 
control data set contains the PUNCH, RECORD, and LABELS statements. 

• PUNCH initiates the punch operation, indicates that one FIELD parameter is 
included in a subsequent RECORD statement, and assigns a sequence number 
for the first punched card (00000000) and an increment value for successive 
sequence numbers (20). Sequence numbers are placed in columns 73 through 
80 of the output records. 

• RECORD indicates that bytes 1 through 72 of the input records are to be 
punched. Bytes 73 through 80 of the input records are replaced by the new 
sequence numbers in the output card deck. 

• LABELS specifies that user header labels and user trailer labels are to be 
punched. 

Labels cannot be edited; they are always moved to the first 80 bytes of the 
output buffer. In this example, no sequence numbers are present on the cards 
containing user header and user trailer records. 



In this example, the directory of a partitioned data set is to be printed. The input 
data set resides on a 2314 volume. The printed output is to be converted to 
hexadecimal. 

The example follows: 

//PRINTDIR JOB 09#660, SMITH 

// EXEC PGM=IEBPTPCH 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=PDS,UNIT=2314,VOLUME=SER=1 1 1 1 12, 

// DISP=( OLD, KEEP ),DCB=(RECFM=U,BLKSIZE=256 ) 

//SYSUT2 DD SYSOUT=A 

//SYSIN DD * 

PRINT TYPORG=PS , TOTCONV=XE 

TITLE ITEM=( 'PRINT PARTITIONED DIRECTORY OF PDS ' , 1 ) 
TITLE ITEM=( 'FIRST TWO BYTES SHOW NUM OF USED BYTES ', 1 ) 
LABELS DATA=NO 

/* 

The control statements are discussed below: 

• SYSUTl DD defines the input data set (the partitioned directory). 
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IEBPTPCH Example 9 



• SYSUT2 DD defines the output data set on the system output device (printer 
assumed). Each printed line contains groups (8 characters each) of 
hexadecimal information. Six lines of print are required for each record. Each 
record begins a new line of printed output. 

• SYSIN DD defines the control data set, which follows in the input stream. The 
control data set contains the PRINT, TITLE, and LABELS statements. 

• PRINT initiates the print operation, indicates that the partitioned directory is 
organized sequentially, and specifies conversion from alphameric to 
hexadecimal representation. 

• The first TITLE statement specifies a title, which is not converted to 
hexadecimal. 

• The second TITLE statement specifies a subtitle, which is not converted to 
hexadecimal. 

• LABELS specifies that no user labels are to be printed. 

Note: Not all of the bytes in a directory block need contain data pertaining to 
the partitioned data set; unused bytes are sometimes used by the operating 
system as temporary work areas. The first four characters of printed output 
indicate how many bytes of the 256-byte block pertain to the partitioned data 
set. Any unused bytes occur in the latter portion of the directory block; they are 
not interspersed with the used bytes. 



In this example, a card deck containing valid punch card code or BCD is to be 
duplicated. The input card deck resides in the input stream. 

The example follows: 

//PUNCH JOB 09#660, SMITH 

// EXEC PGM= IEBPTPCH 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD DSNAME=PDSLIB(PNCHSTMT),DISP=( OLD, KEEP) 

//SYSUT2 DD UNIT=2540-2 

//SYSUT1 DD DATA 

(input card data set including // cards) 

/* 

The control statements are discussed below: 

• SYSIN DD defines the control data set. The control data set contains a PUNCH 
statement and is defined as a member of the partitioned data set PDSLIB. (The 
data set is cataloged.) The RECFM must be FB and the LRECL must be 80. 

• SYSUT2 DD defines the output data set. The data set is to be punched on an 
IBM 2540-2 Card Read Punch (punch feed). 

• SYSUTi DD defines the input card data set, which follows in the input stream. 



In this example, a record group is to be printed. A user routine is provided to 
manipulate output records before they are printed. 
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The example follows: 

72 
//PRINT JOB 09#660, SMITH 
// EXEC PGM=IEBPTPCH 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=SEQDS,UNIT=2314,DISP=(OLD,KEEP), 
// LABEL=( , SUL),VOLUME=SER=1 1 1 1 1 2 , DCB=( RECFM^FB, 
// LRECL=80,BLKSIZE=2000) 
//SYSUT2 DD SYSOUT=A 
//SYSIN DD * 

PRINT MAXFLDS=2,MAXGPS=1 ,MAXLITS=6 , STOPAFT=32767 
TITLE ITEM=( ' TIMECONV-DEPT D06 ) , ITEM=( JAN1 0-1 7 ' , 80 ) 
EXITS OUTREC=NEWTIME , INHDR-HDRS , INTLR=TLRS 
RECORD IDENT=( 6, '498414' , 1 ), C 

FIELD=(8, 1 , , 10 ),FIELD=( 30,9,XE,20 ) 
LABELS DATA=ALL , CONV=XE 
/* 

The control statements are discussed below: 

• SYSUTl DD defines the input data set. The data set resides on a 2314 volume. 

• SYSUT2 DD defines the output data set on the system output device (printer 
assumed). 

• SYSIN DD defines the control data set, which follows in the input stream. The 
control data set contains the print, title, EXITS, and RECORD statements. 

• The print statement: (1) initializes the print operation, (2) indicates that two 
FIELD parameters are included in subsequent RECORD statements, (3) indicates 
that one IDENT parameter is included in a subsequent RECORD statement, (4) 
indicates that six literal characters are included in the subsequent IDENT 
parameter, and (5) indicates that processing is to be terminated after 32,767 
records are processed or after the first record group is processed, whichever 
comes first. Because MAXLINE is omitted, 60 lines are printed on each page. 

• TITLE specifies a title. 

• EXITS specifies the name of a user routine (NEWTIME), which is used to 
manipulate output records before they are printed. 

• RECORD defines the record group to be processed and indicates where 
information from the input records is placed in the output records. Bytes 1 
through 8 of the input records appear in columns 10 through 17 of the 
punched output, and bytes 9 through 38 are printed in hexadecimal 
representation and placed in columns 20 through 79. 

• LABELS specifies that all user header or trailer labels are to be printed 
regardless of any return code, except 16, issued by the user's exit routine. It 
also indicates that the labels are to be converted from alphameric to 
hexadecimal representation. 
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IEBTCRIN Program 



IEBTCRIN is a data set utility used to read input from the IBM 2495 Tape 
Cartridge Reader (TCR), edit the data as specified by the user, and produce a 
sequentially organized output data set. (See "Introduction" for general data set 
utility information.) 

The input to IEBTCRIN is in the form of cartridges written by either the IBM 
Magnetic Tape SELECTRIC Typewriter (MTST) or the IBM 50 Magnetic Data 
Inscriber (MTDI). An input data set (one or more cartridges) must consist of 
either all mtst cartridges or all mtdi cartridges. 

IEBTCRIN can be used to construct records from the stream of data bytes read 
sequentially from the Tape Cartridge Reader. The user has the option of gaining 
temporary control (via a user-supplied exit routine) to process each logical 
record. 

When MTDI input is edited, IEBTCRIN maintains information about each record 
as it is being edited. This information is summarized in the Error Description 
Word (EDW) which is described below. When the EDW contains a value other 
than zero in either the level status (byte 0) or the type status (byte 1), the 
record is considered an error record by the program and the EDW is appended to 
the start of the record to aid the user in analyzing the error. 



Error Records 



If a record is found to be in error, the record is passed to the user error exit 
routine if one is specified. If an error exit is not specified, the action to be taken 
is determined by the option specified in a utility control statement. 

When either MTST input or MTDI input without editing is specified, the only 
error that can be recognized is a record containing one or more permanent data 
checks. The data check bytes are replaced as described in a utility control 
statement. The record is considered an error record, but because a data check is 
the only error that can occur, no EDW is appended to the error record. 

Error Description Word (EDW) 

The Error Description Word (EDW) consists of four bytes that are appended to 
the start of an error record. 

The error description word is in EBCDIC format; for example, a 2 is represented 
as XT2' and a C is represented as X'C3'. The information provided in each of 
the four bytes of the EDW is discussed below. 



Level Status (Byte 0) 



The level status indicator identifies error records that result from interrecord 
dependency that cannot be identified in the type status byte. 

The level status is presented with each error record and has a value of: 

• 0, for any error record that will not cause questionable data in following 
records. A type status other than zero accompanies this byte. 

• 1, for any error record that may cause questionable data in following records, 
and for which the level status of the previous record was 0. 
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Type Status (Byte 1) 



Start of- Record (Byte 2) 



• 2, for any error record that contains questionable data because the error level 
of the preceding record was 1 or 2, or for any error record that may cause 
questionable data in the following records and for which the level status of the 
previous record was 1 or 2. 

A level status of other than is presented with error records resulting from the 
following: 

• The start-of-record (SOR) location has a character defined as an error. 

• The record contains two or more data check bytes side by side. These may 
have been an SOR and EOR. 

• The record is longer than the user-specified maximum length record. 

• The length of the record is not equal to the length of the first valid record of 
the same program level encountered on this cartridge. For this purpose, a valid 
record is one that contains no errors as identified in the type status, with the 
possible exception of being shorter than the user-specified minimum length. 

• The record has a data-duplication dependency on a previous record with one 
of the above errors. 

The level status is set to when IEBTCRIN encounters: (1) a record without one 
of the previous errors, (2) a canceled record, or (3) the first record of a 
cartridge. 



The type-status indicator identifies records in error because of SOR, EOR, length, 
field, or data check error conditions. 

The type status is presented with each error record and has a value of: 

• 0, for any record that contains none of the following identifiable errors, but 
contains questionable data due to a level status other than zero. (See "Level 
Status" earlier in this chapter.) 

• 1, for any record that has: (1) an SOR character of other than PI through P8 
or a GS code, (2) an EOR character of other than a VOK code for records 
when the user specified a record verification check, or (3) an EOR character of 
other than a VOK or RM code for records when the user specified no 
record-verification check. 

• 2, for any record that has an incorrect length because it is: (1) longer than the 
user-specified maximum, (2) shorter than the user-specified minimum, or (3) 
not equal to the length of the first valid record of the same program level 
encountered on this cartridge. 

• 4, for any record that has a field error. A field error occurs when duplication 
or left-zero justification functions did not occur in a field due to an error 
condition. See "MTDI Editing Criteria" below. 

• 8, for any record that has a permanent data check error. 

The type-status indicator can also have values of 3, 5, 6, 7, 9, A, B, C, D, E, 
and F. These values indicate a combination of SOR, EOR, length, field, and data 
check errors. For example, a value of A indicates a record with a data check 
error (8) as well as an incorrect length (2). 



This byte contains an indication of the start-of-record (SOR) character associated 
with this record. The SOR character can be 1 through 8, where 1 indicates PI, 2 
indicates P2, etc., or E, which indicates that the SOR character is in error. 
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End-of -Record (Byte 3) 



This byte contains an indication of the end-of-record (EOR) character associated 
with this record. The EOR character can be: u, which indicates an unverified 
record; V, which indicates a verified record; or E, which indicates that the EOR 
character is in error. 



Sample Error Records 



Figure 12-1 shows a stream of data bytes read sequentially from the tape 
cartridge reader. 

Figure 12-2 shows the records constructed by IEBTCRIN from the input records 
shown in Figure 12-1. These records show some of the errors that can occur 
during processing and their effect on the Error Description Word. The following 
parameters were specified for these records: 



TCRGENTYPE=MTDI,EDIT=EDITR,VERCHK=VOKCHK f 
MAXLN=50 , REPLACE=X ' 5B ' 



72 
C 



p v 

111372 RECORD NUMBER 1AO 
1 K 



* DDDDDDDDDDDDDDD DV 
•111 378UUUUUUUUUUUUUUU2UO 

* PPPPPPPPPPPPPPP PK 





P DDDDDDDDDDDDDDD DV 

357987UUUUUUUUUUUUUUU3UO 

1 PPPPPPPPPPPPPPP PK 



P * V 

358977 REC*RD NUMBER 4AO 

1 * K 





P R 

358436 RECORD NUMBER 5 
1 M 



P DDDDDDDDDDDDDDD DV 

3 584 36UUUUUUUUUUUUUUU6UO 

1 PPPPPPPPPPPPPPP PK 




Figure 12-1. Tape Cartridge Reader Data Stream 
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(Record 1 ) 





V 
P 
1111372 RECORD NUMBER 1AK 


(Record 


3) 


201V 


V 
P 
1357987 RECORD NUMBER 3AK 


(Record 


5) 


131U 


P R 
1358436 RECORD NUMBER 5M 



(Record 2) 



19EV 



V 

O 

$111378 RECORD NUMBER 2AK 



(Record 4) 



081V 



V 
P O 

1358977 REC$RD NUMBER 4AK 



(Record 6) 



241V 



V 
P O 

1358436 RECORD NUMBER 6$K 



(Record 7) 



233E 



(Record 8) 



3998865 RECORD NUMBER 7A MAXIMUM 00001430 IN WAREH 



21EV 


V 

O 

OUSEK 



(Record 9) 



081V 



V 
P O 

1367$82 RECORD NUMBER 8AK 



MAXLN ends here 
(EOR Forced) 



Resulting Error 
Description Word 

Figure 12-2. Record Construction 

IEBTCRIN classifies records 2 through 9 in Figure 12-2 as error records. The 
records are classified, as follows: 

• Record 1 is a valid record. It contains a program-level 1 code, and thus 
establishes the valid length for all program-level 1 records in this cartridge to be 
25 bytes. 

• Record 2 has a data check in the SOR location. Level status is set to 1 because 
the SOR location might have contained a cancel code that would cause any data 
duplicated on the following record to be questionable. The type status (9) 
indicates the record has an incorrect SOR/EOR character ( 1 ) and a data check 
error (8). 

• Record 3 contains no identifiable error, but contains questionable data because 
it requires duplication from the previous record, which had a level status of 1 . 

• Record 4 has a data check. Because it contained no DUP codes, the level status is 
set to 0. 

• Record 5 is shorter than the first program-level 1 record on this cartridge (length 
error). This record also contains an RM code rather than a VOK code in the EOR 
location (VOKCHK was specified). Because IEBTCRIN cannot determine why the 
record is short, all data duplicated from this record is questionable; the level 
status is set to 1 . The type status is set to 3 indicating an SOR/EOR error ( 1 ) and 
length error (2). 

• Record 6 contains a DUP code that is beyond the last position of the preceding 
record. 
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MTDI Editing Criteria 



MTDI Editing Restrictions 



• The seventh input record is longer than the maximum user-specified record 
length. Note that it is passed as two records. The first record (record 7) indicates 
an EOR error and a length error; the second (record 8) indicates an SOR error. 
Because record 7 is an error record, its length (50 bytes) is not established as the 
valid length for all program-level 3 records on this cartridge. 

• Record 9 has a data check. Because it contained no DUP codes, the level status is 
set to 0. 



The cartridges created on the IBM 50 Magnetic Data Inscriber contain a continuous 
stream of data bytes (that is, there are no interblock gaps). Therefore, when editing 
is specified, IEBTCRIN extracts records one at a time from the data stream. To 
accomplish this, IEBTCRIN scans for control codes written by MTDI. IEBTCRIN uses 
start-of -record (SOR) and end-of -record (EOR) locations to extract MTDI records 
from the input stream. 

The (SOR) location is defined as: 

• The location of the first character on a cartridge. 

• The location of the first character after the previous record's (EOR) location. 

• The location of an SOR code. 

• The location of a GS code. 

The character in the SOR location is checked to determine if it is a valid 
start-of -record character. A PI through P8, a cancel code, or a GS code are valid 
start-of -record characters; all others are invalid. 

The EOR location by priority sequence is: 

1 . The same location as the SOR location, if the SOR character was a valid GS code. 

2. The location of the first encountered RM or VOK code if that location is within 
the length of the maximum user-specified record size. 

3. The location of any code preceding either a valid SOR code or the end-of -media 
code, if that location is within the length of the maximum user-specified record 
size. 

4. The location determined in 2 or 3, regardless of the maximum user-specified 
record size if the SOR location contains a cancel code. 

5. If one of the previous EOR locations cannot be defined, an EOR condition will be 
forced at the location where the record length equals the maximum 
user-specified record size. 

The character in the EOR location is checked to determine if it is a valid 
end-of -record character. Valid EOR characters are the GS character (if the SOR 
character was a GS code) and VOK or RM codes; all others are invalid. Each GS 
code is considered a valid SOR code or EOR code and will be bypassed. 



Following are the restrictions that apply when editing MTDI records: 

• All canceled records are bypassed; they are not passed to any exit routines or 
written on any data sets. The level status is set to 0. 

• All input records less than three bytes in length (SOR location, one data byte., 
and EOR location) are treated as canceled records. The remaining portion of a 
record that was longer than the user-specified maximum record size can result in 
an input record of this size. 
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End-of-Cartridge 



Input and Output 



• Data duplication is accomplished by replacing the DUP code with the character 
from the corresponding location of the previous record. 

• The record used for data duplication is the record returned from any user exits. 

• GS codes will not affect the level status or duplication of following records. 

• Data duplication does not occur for any of the following conditions: 

1 . The DUP code is encountered in the first record of a cartridge. 

2. The DUP code is encountered in a record immediately following a canceled 
record. A canceled record is one that contains a cancel code in the SOR 
location or an input record of less than three bytes as described above. 

3. The DUP code is encountered in a position that would cause duplication of a 
position beyond the last data byte of the previous record. 

4. The DUP code is encountered in a position that would cause duplication of an 
error-replace character. 

In each case, the DUP code is replaced with the user specified error-replace 
character, and a field error is indicated. 

• Left-zero justification does not occur; the left-zero fill code (LZ) is replaced with 
the user-specified error-replace character and a field error is indicated for either 
of the following conditions: 

1. The left-zero fill code (LZ) is encountered without first having encountered its 
corresponding left-zero start code (LZS). 

2. The user-specified maximum record size is exceeded before encountering the 
valid end of a left-zero field. 



Unique codes, written by the MTST or the MTDI device, signal the program when all 
data on a cartridge has been read. For MTST cartridges, this end-of -cartridge code 
is a lowercase stop code (st) or an uppercase stop code (ST). For MTDI cartridges, 
the end-of-cartridge code is the end-data code (ED). 

IEBTCRIN terminates input from a cartridge upon encountering the end-of-cartridge 
code and rewinds the cartridge. IEBTCRIN continues to process cartridges until 
end-of -file is encountered. 

End-of -file is signaled following a rewind operation when there are no more 
cartridges in the feed hopper, the END OF FILE button is pressed, and 
end-of-cartridge for the last cartridge is recognized. An end-of -file indication will 
be passed to the OUTREC and/or ERROR exits if specified by setting register 1 
equal to 0. 



IEBTCRIN uses the following input: 

• An input data set, which contains data on tape cartridges to be read from the 
Tape Cartridge Reader (TCR). The input data set was created on either MTST or 
MTDI. 

• A control data set, which contains utility control statements that are used to 
control the functions of IEBTCRIN. 
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Control 



IEBTCRIN produces the following output: 

• An output data set, which contains the sequential output produced by the utility 
as a result of processing the cartridge input according to the utility control 
statements. 

• An error output data set, which contains records that do not conform to the 
specifications for a valid record. 

• A message data set, which contains diagnostic messages. 



IEBTCRIN is controlled by job control statements and utility control statements. 
The job control statements are required to execute or invoke IEBTCRIN and to 
define the data sets that are used and produced by the program. The utility control 
statements are used to indicate the source of the input data cartridges (MTST or 
MTDI) and to specify the type of processing to be done. 



Job Control Statements 



Table 12-1 shows the job control statements necessary for using IEBTCRIN. 

Table 12-1. iebtcrin Job Control Statements 

Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (PGM=iebtcrin) or, if the job control statements 

reside in a procedure library, the procedure name. 

SYSPRINT DD Defines a sequential message data set, which can be written to any 
QSAM-supported output device. 

SYSUT1 DD Defines the input data set. 

SYSUT2 DD Defines a sequential output data set for valid records. 

SYSUT3 DD Defines a sequential output data set for error records. 

SYSIN DD Defines the control data set. The control data set normally resides in the input 

stream; however, it can be defined as a sequential data set or as a member of 
a partitioned data set. If this statement is not included, all utility control 
statement defaults are assumed and a message is issued to SYSPRINT. If 
dummy is specified, all utility control statement defaults are assumed. 

If the SYSPRINT DD statement is missing, a message is written on the operator 
console and processing continues. 

If some parameters are specified but others are omitted, IEBTCRIN attempts to set 
defaults for the missing parameters that are consistent with those supplied. For 
example, if RECFM=VBA is specified, IEBTCRIN assumes BLKSIZE=129 and 
LRECL=125. If lrecl, blksize, and RECFM are not specified, the defaults are 

LRECL=121, BLKSIZE=121, and RECFM=FBA. 

For the SYSUT1 DD statement, only the UNIT keyword is required. The value 
specified in UNlT=xxxx can be '2495', the device address, or any other name that 
was generated in the system as a unit device name. The VOLUME=SER= keyword 
may be specified to identify the tape cartridges to be mounted. The volume serial 
number must be an externally recognizable name associated with the cartridges to 
be processed. A message is issued to the operator instructing that the cartridges 
identified by that name be mounted. If VOLUME is not specified, the name TCRINP 
is assumed and used in the mount message. The BUFL DCB parameter can be 
specified to indicate the size of input buffers; if BUFL is not specified, a value of 
2000 is assumed. 

Fixed and variable records on the SYSUT2 or SYSUT3 data set can be blocked 
through the specification of the BLKSIZE and RECFM DCB parameters. 
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Restrictions 



SYSUT2 dd and SYSUT3 DD statements may be omitted or specified as dummy. A 
message is issued on SYSPRINT and processing continues. 

The DCB parameters defining the SYSIN, SYSPRINT, SYSUT2, and SYSUT3 data sets 
can be supplied from any valid source (for example, DD statements or a data set 
label). Because the output (SYSUT2 and/or SYSUT3) data sets are not opened until 
the first record is ready for output (after any OUTREC and/or ERROR exits), DCB 
parameters to be supplied from an existing data set label are not available for 
records constructed before the data set is opened. Therefore, the DCB parameters 
should always be provided in the DD statement even though they may already exist 
in the label. Otherwise, defaults are used to construct records until the data set is 
opened. 

If a permanent error occurs on SYSIN, SYSUTl (not including a data check), 
SYSUT2, or SYSUT3, a message is issued on sysprint and the program is 
terminated. If a permanent input/output error occurs on SYSPRINT, both the failing 
message and a SYNADAF message indicating the error, are written on the 
programmer's console and processing is terminated. 



• Because IEBTCRIN always constructs the SYSPRINT records with USASI (type A) 
control characters, type A control characters should be indicated when RECFM is 
specified. 

• If a parameter is specified on SYSPRINT DD that is not consistent with the other 
parameters, a message is issued and processing is ended. 

• The SYSUTl DD statement is required for each use of IEBTCRIN. 

• The SYSUT2 DD and SYSUT3 DD statements must identify sequential data sets; 
the data sets can have fixed, variable, variable spanned, or undefined records. 
These data sets can be written on any QSAM-supported device. 

• If editing of MTDI input is specified on the utility control statements, the SYSUT3 
LRECL parameter should be four bytes greater than the SYSUT2 lrecl 
parameter to include a four bytes long Error Description Word appended to the 
front of the record by iebtcrin. (See "Error Records" earlier in this chapter.) 
For variable records on either SYSUT2 or SYSUT3, the LRECL and BLKSIZE DCB 
parameters must be large enough to include the four bytes long record descriptor 
word. 

• If inconsistent parameters are specified on SYSUT2 DD or SYSUT3 DD, a message 
is issued and processing is ended. 

Utility Control Statements 

IEBTCRIN is controlled by the following utility control statements: 

• TCRGEN statement, which specifies whether MTDI or MTST input is to be 
processed and the type of processing to be performed. 

• EXITS statement, which specifies any exit routines provided by the user. 

If these statements contain errors or inconsistencies, the program is terminated and 
the appropriate diagnostics are sent to the message data set. If TCRGEN is not 
specified, standard defaults are used. 



TCRGEN Statement 



The TCRGEN statement is used to indicate the device (MTDI or MTST) on which the 
input data was created and the type of processing to be performed on the input 
data. 
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The format of the TCRGEN statement is: 

[label] [TCRGEN TYPE= {MTDI} 

{MTST}] 

[,TRANS={STDUC } 
{STDLC } 

{name } 
{NOTRAN}] 

[,EDIT={EDITD} 
{EDITR } 
{NOEDIT}] 

[, VERCHK= {NOCHK} 
{VOKCHK}] 

[,MINLN=n] 
[,MAXLN=n] 
REPLACE=X'xx' 
[,ERROPT= {NORMAL} 
{NOERR}] 

where: 

TYPE= 

specifies the device on which the magnetic tape cartridge(s) was written. These 
values can be coded: 

MTDI 

specifies that the input was created on a Magnetic Data Inscriber. If no value 
is specified, MTDI is assumed. 

MTST 

specifies that the input was created on a Magnetic Tape SELECTRIC 
typewriter. 

TRANS= 

specifies the type of processing to be performed on MTST input. These values 
can be coded: 

STDUC 

specifies that the MTST code is to be translated to standard EBCDIC; 
alphabetic characters are translated to uppercase. This is the default. 

STDLC 

specifies that the MTST code is to be translated to standard EBCDIC; 
alphabetic characters are not translated to uppercase. 

name 

specifies a user translate table to be used by IEBTCRIN. The translate table 
must exist as a load module named in a user job library or the link library. 
This load module must consist of a translate table which begins at the entry 
point and conforms to the specifications for the translate instruction (TR) 
found in IBM System/370 Principles of Operation, GA22-7000. 

NOTRAN 

specifies that no translation and no special processing is to be performed. 
Data is passed exactly as read from the cartridge. 
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EDIT= 

specifies the type of processing to be performed on MTDI input. These values 
can be coded: 

EDITD 

specifies that the input is to be edited and that SOR and EOR codes are to be 
deleted and not included as part of the output record. 

EDITR 

specifies that the input is to be edited and SOR and EOR codes are to be kept 
as part of the output record. 

NOEDIT 

specifies that no editing is to be performed. Data, including any group 
separator (GS) codes, is passed exactly as read from the cartridge. 

VERCHK= 

specifies whether a record-verification check is to be made on MTDI input that is 
to be edited. This parameter is valid only when TYPE=MTDI and either 
EDIT=EDITD or EDIT=EDITR are specified. These values can be coded: 

NOCHK 

specifies that no record- verification check is to be made. Either a record mark 
(RM) or a verify OK (VOK) code is considered a valid end-of-record code. This 
is the default. 

VOKCI1K 

specifies that a record- verification check is to be made. A record that does 
not contain a verify OK code is to be considered an error record. 

MINLN=n 

specifies in bytes the length, n, of the shortest valid, edited record. This 
parameter is valid only when TYPE=MTDI and either EDIT=EDITD or 
EDIT=EDITR are specified. If IEBTCRIN encounters a record shorter than this 
specified length, the record is considered an error record. If MINLN is omitted, 
no minimum length checking is performed. 

MAXLN=n 

specifies the number of bytes, n, plus four for the record descriptor word when 
variable records are specified, to be contained in all but the last record passed to 
the output routine when editing is not performed. IEBTCRIN does not indicate 
the end of data from one cartridge and the beginning of data from the next. 
Usually this transition from one cartridge to another occurs within an output 
record. The last record passed to the output routine contains only the number of 
bytes remaining (plus four if the record format is variable) and is the only record 
that can be shorter than the length specified by MAXLN. The size of the records 
actually written depends on the record length (LRECL) specified for the output 
data set. If MAXLN is omitted, a value of 120 is assumed. 

REPLACE=X'xx' 

specifies the hexadecimal representation of the character to be used by 
IEBTCRIN to replace error bytes. REPLACE allows the user to identify and 
possibly correct error bytes in the error exit routine or in subsequent processing. 
The specified REPLACE character should be one that does not normally appear in 
the data. X'19\ end-of-data, is assumed if REPLACE is not coded. To replace 
error bytes on MTDI data, select a value for xx from Figure 12-3. To replace 
error bytes on MTST data, select a value for xx from Figure 12-4. The 
replacement of error bytes is accomplished before any specified MTST 
translation. 
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ERROPT= 

specifies the disposition of all error records. ERROPT is ignored if a user error 
routine is specified in the EXITS statement. These values can be coded: 

NORMAL 

specifies that all error records are to be placed in the error data set (SYSUT3). 

NOERR 

specifies that all records (including error records) are placed in the normal 
output data set (SYSUT2). No records are placed in the error data set 
(SYSUT3). This is the default. 

If STDUC, STDLC, or name is specified, certain of the MTST codes are processed in a 
special way before translation. Feed codes (FD), switch codes (SW), and autosearch 
codes (AS), both uppercase and lowercase, are deleted from the data. Each 
61 -character reference code is reduced to a single search code (SRC). 

A stop code, whether uppercase (ST) or lowercase (st), indicates that all data on a 
cartridge has been read. Therefore, when an MTST cartridge to be processed by 
IEBTCRIN is created, the user must not use a stop code for any purpose other than 
signaling end-of-data on the cartridge. Stop codes within meaningful data cause any 
subsequent data on the cartridge to be lost because the cartridge is rewound and 
unloaded when a stop code is encountered. 

If EDITD or EDITR is specified, the edit consists of the following functions: 

• Records are extracted one at a time from the input buffers by scanning for the 
record-delimiting codes (SOR and EOR). 

• DUP codes are replaced with the character from the corresponding location in 
the preceding record. 

• Left-zero fields are right aligned and leading zeros are inserted where necessary. 

• Left-zero start codes are deleted from the records. 

• Group separator codes and records that start with cancel record codes are 
bypassed. 

For MTDI input with editing specified, MAXLN is used to specify in bytes the length 
of the longest valid record after editing. If the program encounters a record in 
which a valid end-of-record cannot be determined within this length, an 
end-of -record condition is forced and the record is considered an error record. 

The values that can be specified for MINLN and MAXLN are: 

• For MTST processing or MTDI processing without editing, MINLN is not specified. 
MAXLN should equal the number of bytes to be passed as a record. 

• For MTDI processing when EDIT=EDITD, MINLN should equal the number of 
bytes in the shortest valid record after editing, excluding SOR and EOR codes. 
MAXLN should equal the number of bytes in the longest valid record after 
editing, excluding SOR and EOR codes. 

• For MTDI processing when EDIT=EDITR, MINLN should equal the number of 
bytes in the shortest valid record after editing, including SOR and EOR codes. 
MAXLN should equal the number of bytes in the longest valid record after 
editing, including SOR and EOR codes. 

Note: The values for MINLN and MAXLN should not include the four bytes long 
record descriptor word added to a variable length record. 

Table 12-2 shows the hexadecimal characters representing special purpose codes 
that must not be used as replacement bytes. 
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Table 12-2. Special Purpose Codes 



MTDI Codes 










X'OO' 


(LZ) 


X'lE' 


(VOK) 


X'74' 


(P4) 


X'lT 


(DUP) 


X'3C 


(RM) 


X'75' 


(P5) 


X'12' 


(LZS) 


X'71' 


(PI) 


X'76' 


(P6) 


X'18' 


(CAN) 


X'72' 


(P2) 


X'77' 


(P7) 


X'lD' 


(GS) 


X'73' 


(P3) 


X'78' 


(P8) 


MTST Codes 










X'lO' 


(cr) 


X'14' 


(CR) 


X'51' 


(as) 


X'll' 


(sw) 


X'15' 


(SW) 


X'55' 


(AS) 


X'13' 


(fd) 


X'17' 


(FD) 


X'80' 


(src) 
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B 


C 


D 


E 


F 
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SP 


& 
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/ 
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A 
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1 
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B 


K 


S 


2 
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P3 










C 


L 


T 


3 


0100 
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P4 










D 


M 


U 


4 
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E 


N 


V 


5 
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w 


6 
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P7 










G 


P 


X 


7 
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This figure represents the character set and control 
codes as read from an MTDI created cartridge. 



Figure 12-3. MTDI Codes from TCR 



Bit Positions 0, 1 
Bit Positions 2, 3 
First Hexadecimal Digit 



Special Control: 

LZ = Left zero fill 

DUP = Duplicate 

LZS = Left zero start 

ED = End data 

GS = Group Separator 



Start of Record (SOR): 



P1 = 
P2 = 
P3 = 
P4 = 
P5 = 
P6 = 
P7 = 
P8 = 
CAN 



Program level 1 
Program level 2 
Program level 3 
Program level 4 
Program level 5 
Program level 6 
Program level 7 
Program level 8 
= Cancel 



End of Record (EOR): 

RM = Record mark 
VOK = Verify OK 



The special purpose codes listed in Table 12-2 are used by IEBTCRIN when 
constructing records. Use of these codes causes a message to be issued and the 
utility to be terminated. 
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Figure 12-3 shows the values that can be chosen to replace error bytes for MTDl 
input. 

Figure 12-4 shows the values that can be chosen to replace error bytes for MTST 
input. 
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This figure represents the character set and control 
codes as read from an MTST created cartridge. 

Figure 12-4. MTST Codes from TCR 



Bit Positions 0, 1 
Bit Positions 2, 3 

First Hexadecimal Digit 



cr and CR 
sw and SW 
fdand FD 
st and ST 
tab and TAB 
as and AS 
sp and SP 
bsp and BSP 
stx and STX 
src and SRC 



Carrier return code 

Switch code 

Feed code 
: Stop code 

Tab code 

: Automatic search 
: Space 
: Backspace 
; Stop transfer 
: Search 
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Figure 12-5 shows MTST codes after they have been translated by IEBTCRIN when 
TRANS=STDLC is specified. 
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Bit Positions 0,1 
Bit Positions 2, 3 
First Hexadecimal Digit 



TAB = Tab code 
CR = Carrier return 
BSP = Backspace 
SRC = Search 
STX = Stop transfer 
SP = Space 

Note: The STDUC option permits translating 
both lowercase and uppercase alphabetic 
characters to uppercase. 

Figure 12,-5. MTST Codes after Translation by iebtcrin with trans = stdcl 

EXITS Statement 

The EXITS statement is used to identify user-supplied exit routines, which must 
exist in either the user job library or the link library. 

Upon entry, a parameter list is supplied to the exit routine. Upon returning from the 
exit routine, the user must provide an acceptable return code. See "Appendix A: 
Exit Routine Linkage." 
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The format of the EXITS statement is: 

[label] EXITS [ERROR =routinename] 
[,OUTREC = routinename] 
[,OUTHDR2 = routinename] 
[,OUTHDR3 = routinename] 
[,OUTTLR2 = routinename] 
[,OUTTLR3 = routinename] 

where: 

ERROR = routinename 

specifies the symbolic name of a routine that receives control before an error 
record is passed to the error output data set (SYSUT3). This exit routine can be 
used to analyze and, if possible, correct the error record. This parameter nullifies 
any ERROPT value. 

OUTREC = routinename 

specifies the symbolic name of a routine that receives control before the record 
is passed to the normal output data set (SYSUT2). In this exit routine, the user 
can process the record and perform his own output if output other than the 
SYSUT2 data set is desired. Any modification of an edited MTDI record may 
affect the editing of following records. The record returned from this exit is used 
to accomplish data duplication in the record that follows. If the SYSUT2 data set 
has specified variable length records, an RDW which is four bytes long is 
appended to the front of the record. 

OUTHDR2 = routinename 

specifies the symbolic name of a routine that receives control during the opening 
of the SYSUT2 data set; this exit routine can be used to create user output header 
labels for the normal output data set (SYSUT2). 

OUTHDR3 = routinename 

specifies the symbolic name of a routine that receives control during the opening 
of the SYSUT3 data set; this exit routine can be used to create user output header 
labels for the error data set (SYSUT3). 

OUTTLR2 = routinename 

specifies the symbolic name of a routine that receives control during the closing 
of the SYSUT2 data set; this exit routine can be used to create user output trailer 
labels for the normal output data set (SYSUT2). 

OUTTLR3 = routinename 

specifies the symbolic name of a routine that receives control during the closing 
of the SYSUT3 data set; this exit routine can be used to create user output trailer 
labels for the error data set (SYSUT3). 

If MTDI is edited, an EDW which is four bytes long is appended to the front of each 
error record describing the error condition. For further definition of the EDW, see 
"Error Records" earlier in this chapter. If the SYSUT3 DD statement specified 
variable length records, an RDW which is four bytes long is also appended to the 
front of the record. For further description of the RDW, see OS/VS Supervisor 
Services and Macros, GC27-6979. 

The user-supplied routines specified in error and OUTREC can be used to examine 
and modify any byte in the record or EDW. The record length can be changed, 
subject to the following restrictions: 

• A work area used to construct the records is allocated by the program equal in 
size to the largest of (1) maxln, (2) LRECL on SYSUT2, or (3) LRECL on 

SYSUT3. 
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• The record length must not be increased beyond this size. Overlaying of other 
work areas may then occur, causing unpredictable results. 

The new record length must be placed in the location pointed to by the second 
parameter word as received at entry to the routine. This length must include the 
EDW and RDW (if applicable). It is not necessary to modify the RDW because it is 
re-created if the record is to be written by IEBTCRIN. However, if the user does his 
own output from this routine, he must ensure that the RDW is correct for the 
record. 

If IEBTCRIN is to write the record, the length of the output record depends on the 
RECFM specification, as follows: 

• Fixed and variable records may have a maximum length equal to LRECL. 
Records larger than this are truncated. 

• Undefined records may have a maximum length equal to blksize. Records 
larger than this are truncated. 

These record lengths include the EDW and RDW, where applicable. 

The record length returned from the error exit is used to establish the location of 
the last data byte in the record. The location is used to control data duplication in 
the following record. However, it is not used for checking the record length of 
subsequent records. 

Modifications to the EDW, record, or record length may affect the editing of 
subsequent records. If the input is not edited, the user can examine and modify any 
byte in the record. The record length can also be changed, subject to the 
MTDl-editing restrictions. 
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At job termination, IEBTCRIN produces a return code to indicate the results of 
program execution. Table 12-3 shows the return codes used by IEBTCRIN. 

Table 12-3. IEBTCRIN Return Codes 



Return 
Code 

00 

04 



12 



16 



Interpretation 

Normal termination. 

Warning message issued; execution permitted. Conditions leading to issuance of this 
code are: (1) sysprint, sysin, SYSUT2, or SYSUT3 DD statements missing and (2) dcb 
parameters missing in SYSUT2 or SYSUT3 DD statements. 

Diagnostic error message issued; execution terminated. Conditions leading to issuance 
of this code are: (1) SYSUTl DD statement missing, (2) conflicting DCB parameters in 
DD statements, and (3) invalid or conflicting utility control statements. 

Terminal error message issued; execution terminated. Conditions leading to issuance 
of this code are: (1) permanent input/output errors (not including data checks on the 
tcr), (2) unsuccessful opening of data sets, (3) requests for termination by user exit 
routine, (4) insufficient storage available for execution, and (5) user exit routine not 
found. 



IEBTCRIN Examples 



The following examples illustrate some of the uses of IEBTCRIN. Table 12-4 can be 
used as a quick reference guide to IEBTCRIN examples. The numbers in the 
"Example" column point to examples that follow. 
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Table 12-4. iebtcrin Example Directory 



IEBTCRIN Example 1 



IEBTCRIN Example 2 



Operation 

Edit MDTI input 

Invoke IEBTCRIN 
with LINK macro 
instruction 



Data Set 
Organization Device 



Comments 



Example 



Sequential 2314 Disk, Fixed blocked output. Error 

9-track Tape exit routine specified 



In this example, input from a tape cartridge is to be edited with normal records 
written to a 2314 volume and error records written to a 9-track tape volume. 

The example follows: 

// JOBNAME JOB , SMI TH , MSGLEVEL= 1 

//STPNAME EXEC PGM=IEBTCRIN 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD UNIT=TCR,VOLUME=SER=MYTAPE,DCB=(BUFL=3000) 

//SYSUT2 DD DSNAME=GOODSET,DISP==(NEW,CATLG),UNIT=2314, 

// VOLUME=SER=1 1 1 222 , SPACE=( TRK, ( 10,10) ) , DCB=( LRECL=1 00 , 

// BLKSIZE=1000,RECFM=FB) 

//SYSUT3 DD DSNAME=ERRSET,UNIT=2400,VOLUME=SER=000001 , 

// DISP=( NEW, KEEP ) ,DCB=( BLKSIZE=1 04 ,RECFM=U ) 

//SYSIN DD * 

TCRGEN TYPE=MTDI , EDIT=EDITD , MAXLN= 1 00 , REPLACE=X ' 5B ' 

EXITS ERROR=MYERR 
/* 

The control statements are discussed below: 

• SYSUTl DD defines the input tape cartridge data set. A console message instructs 
the operator to mount a set of cartridges named MYTAPE. ' The two input buffers 
are each 3000 bytes long (BUFL). The UNIT parameter assumes that TCR has 
been system generated as a unit name for the Tape Cartridge Reader. 

• SYSUT2 DD defines a sequential data set for the normal output records. The data 
will be written to a 2314 volume. 

• SYSUT3 DD defines a sequential data set for the error records. The records are 
undefined with a maximum block size of 104 bytes, including a 4-byte error 
description word. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• TCRGEN indicates MTDI input. The input is to be edited with SOR and EOR 
codes deleted, the maximum valid record length is to be 100 bytes, and the 
replace character is a hexadecimal "5B". VERCHK is defaulted to NOCHK. 
Minimum record-length checking is not requested. 

• EXITS indicates that a user has provided an exit routine to handle error records. 
Because no job library has been specified, the exit routine (MYERR) must reside 
in the link library. 



In this example, IEBTCRIN is invoked via the LINK macro instruction in an 
Assembler language program. An alternate name has been assigned to each of the 
DD statements used by IEBTCRIN. The job control for this step must include DD 
statements with the alternate DD names. 
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The example follows: 



OPTLIST 



DDNAME 



LINK 

CNOP 

DC 

CNOP 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 



EP=IEBTCRIN , PARAM=( OPTLIST , DDNAME ) , VL= 

2 , 4 (OPTLIST must be on halfword boundary) 

H ' ' (Length must be zero for IEBTCRIN) 

2 , 4 (DDNAME list must be on halfword boundary) 

H'82' (Length of DDNAME list) 

8F'0' 

(Alternate DDNAME for SYSIN) 
(Alternate DDNAME for SYSPRINT) 



C'NEWIN 
C'NEWPRINT 
2F'0' 
CNEWUT1 
C ' NEWUT2 
C ' NEWUT3 



(Alternate DDNAME for SYSUT 1 ) 
(Alternate DDNAME for SYSUT2) 
(Alternate DDNAME for SYSUT3) 
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IEBUPDTE Program 



IEBUPDTE is a data set utility used to incorporate IBM and user-generated source 
language modifications into sequential or partitioned data sets. (See 
"Introduction" for general data set utility information.) Exits are provided for 
user routines that process user header and trailer labels. 

IEBUPDTE can be used to: 

• Create and update symbolic libraries. 

• Incorporate changes to partitioned members or sequential data sets. 

• Change the organization of a data set from sequential to partitioned or vice 
versa. 

At the completion or termination of IEBUPDTE, the highest return code 
encountered within the program is passed to the calling program. 

Creating and Updating Symbolic Libraries 

IEBUPDTE can be used to create a library of partitioned members consisting of 
(at the most) 80-byte logical records. In addition, members can be added directly 
to an existing library, provided that the original space allocations are sufficient to 
incorporate the new members. In this manner, a cataloged procedure can be 
placed in a procedure library, or a set of job or utility control statements can be 
placed as a member in a partitioned library. 

Incorporating Changes 

IEBUPDTE can be used to modify an existing partitioned or sequential data set. 
Logical records can be replaced, deleted, renumbered, or added to the member or 
data set. 

A sequential data set residing on a tape volume can be used to create a new 
master (that is, a modified copy) of the data set. A sequential data set residing 
on a direct access device can be modified either by creating a new master or by 
modifying the data set directly on the volume on which it resides. 

A partitioned data set can be modified either by creating a new master or by 
modifying the data set directly on the volume on which it resides. 

Changing Data Set Organization 

IEBUPDTE can be used to change the organization of a data set from sequential 
to partitioned, or to change a member of a partitioned data set to a sequential 
data set (the original data set, however, remains unchanged). In addition, logical 
records can be replaced, deleted, renumbered, or added to the member or data 
set. 



Input and Output 



IEBUPDTE uses the following input: 

• An input data set (also called the old master data set), which is to be modified 
or used as source data for a new master. The input data set is either a 
sequential data set or a member of a partitioned data set. 

• A control data set, which contains utility control statements and, if applicable, 
input data. The data set is required for each use of IEBUPDTE. 
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IEBUPDTE produces the following output: 

• An output data set, which is the result of the IEBUPDTE operation. The data 
set can be either sequential or partitioned. It can be either a new data set 
(that is, created during the present job step) or an existing data set, modified 
during the present job step. 

• A message data set, which contains the utility program identification, control 
statements used in the job step, modification made to the input data set, and 
diagnostic messages, if applicable. The message data set is sequential. 

IEBUPDTE provides a return code to indicate the results of program execution. 
The return codes and their meanings are: 

• 00, which indicates successful completion. 

• 04, which indicates that a control statement is coded incorrectly or used 
erroneously. If either the input or output is sequential, the job step is 
terminated. If both are partitioned, the program continues processing with the 
next function to be performed. 

• 12, which indicates an unrecoverable error. The job step is terminated. 

• 16, which indicates that a label processing code of 16 was received from a 
user's label processing routine. The job step is terminated. 



Control 



IEBUPDTE is controlled by job control statements and utility control statements. 
The job control statements are required to execute or invoke IEBUPDTE and to 
define the data sets that are used and produced by the program. The utility 
control statements are used to control the functions of IEBUPDTE and, in certain 
cases, to supply new or replacement data. 

Job Control Statements 

Table 13-1 shows the job control statements necessary for using IEBUPDTE. 

Table 13-1. iebupdte Job Control Statements 

Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (PGM=iebupdte), or, if the job control 

statements reside in a procedure library, the procedure name. Additional 
information can be specified in the parm parameter of the exec statement; 
see "parm Information on the EXEC Statement" below. 

SYSPRINT DD Defines a sequential message data set. The data set can be written to a 
system output device, a tape volume, or a direct access volume. 

SYSUT1 DD Defines the input (old master) data set. It can define a sequential data set 

on a card reader, a tape volume, or a direct access volume. Or, it can 
define a partitioned data set on a direct access volume. This DD statement 
is not required if the input consists solely of the control data set. 

SYSUT2 DD Defines the output data set. It can define a sequential data set on a card 

punch, a printer, a tape volume, or a direct access device. It can define a 
partitioned data set on a direct access device. 

SYSIN DD Defines the control data set. The control data set normally resides in the 

input stream; however, it can be defined as a member of a partitioned data 
set. 



The input and output data sets contain blocked or unblocked logical records with 
record lengths of up to 80 bytes. The input and output data sets may have 
different block sizes as long as they are multiples of the logical record length. 
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Restrictions 



If an ADD operation is specified with PARM=NEW on the EXEC card, the SYSUT1 
DD statement need not be coded. See "PARM Information on the EXEC 
Statement" below. Refer to "Function Statement" below for a discussion of the 
ADD operation. 

If an UPDATE operation is specified, the SYSUT2 DD statement should not be 
coded. Refer to "Function Statement" for a discussion of the UPDATE operation. 

If the SYSUTl DD statement defines a sequential data set, the file sequence 
number of that data set must be included in the label keyword (unless the data 
set is the first or only data set on the volume). 

If both the SYSUTl and SYSUT2 DD statements specify standard user labels (SUL), 
IEBUPDTE copies user labels from SYSUTl to SYSUT2. See "Appendix D: 
Processing User Labels" for a discussion of the available options for user label 
processing. 

If the SYSUTl and SYSUT2 DD statements define the same partitioned data set, 
the old master data set can be updated without creating a new master data set; in 
this case, a copy of the updated member or members is written within the extent 
of the space originally allocated to the old master data set. Subsequent referrals 
to the updated member (s) will point to the newly written member(s). The 
member names themselves should not appear on the DD statements; they should 
be referenced only through IEBUPDTE control statements. 



The SYSPRINT DD statement is required for each use of IEBUPDTE. 

The output data set can have a blocking factor that is different from the input 
data set; however, if insufficient space is allocated for reblocked records, the 
update request is terminated. 

When adding a member to an existing partitioned data set using an ADD 
Function statement, any DCB parameters specified on the SYSUTl and SYSUT2 
DD statements (or the SYSUT2 DD statement if that is the only one specified) 
must be the same as the DCB parameters already existing for the data set. 

Space must be allocated for an output data set (SYSUT2 DD statement) that is 
to reside on a direct access device, unless the data set is an existing data set, 
in which case space should not be allocated. 

The SYSUT2 DD statement must not specify a DUMMY data set. 

If the SYSUTl and SYSUT2 DD statements define the same sequential data set 
(direct access only), only those operations that add data to the end of the 
existing data set can be made. In these cases: 

1. The PARM parameter of the EXEC statement must imply or specify MOD. 
(See "PARM Information on the EXEC Statement" below.) 

2. The DISP parameter of the SYSUTl DD statement must specify OLD. 

3. The DISP parameter of the SYSUT2 DD statement must specify MOD. 

The SYSIN DD statement is required for each use of IEBUPDTE. 

The message data set has a logical record length of 121 bytes, and consists of 
fixed length, blocked or unblocked records with an ASA control character in 
the first byte of each record. The input and output data sets have a logical 
record length of 80 bytes or less, and consist of standard fixed blocked 
(RECFM=FB) or unblocked records. The control data set contains 80-byte, 
blocked or unblocked records. 
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PARM Information on the EXEC Statement 

Additional information can be coded in the PARM parameter of the EXEC 
statement, as follows: 

PARM= {NEW},[inhdr],[intlr] 
{ MOD} 

Following are the PARM values: 

• NEW, which specifies that the input consists solely of the control data set. The 
input data set is not defined if NEW is specified. 

• MOD, which specifies that the input consists of both the control data set and 
the input data set. If neither NEW nor MOD is coded, MOD is assumed. 

• "inhdr," which specifies the symbolic name of a routine that processes the 
user header label on the volume containing the control data set. 

• "intlr," which specifies the symbolic name of a routine that processes the user 
trailer label on the volume containing the control data set. 

For a detailed discussion of the processing of user labels as data set descriptors, 
refer to "Appendix D: Processing User Labels." 

Utility Control Statements 

The utility control statements used to control IEBUPDTE are: 

• Function statement, which is used to initiate an IEBUPDTE operation. 

• Detail statement, which is used with the Function statement for special 
applications. 

• Data statement, which is a logical record of data to be used as a new or 
replacement record in the output data set. 

• LABEL statement, which is used to indicate that the following data statements 
are to be treated as user labels. 

• ALIAS statement, which is used to assign aliases. 

• ENDUP statement, which is used to terminate IEBUPDTE. 



Function Statement 



The Function statement is used to initiate an IEBUPDTE operation. At least one 
Function statement must be provided for each member or data set to be 
processed. 

A member or a data set can be added directly to an old master data set if the 
space originally allocated to the old master is sufficient to incorporate that new 
member or data set. 

When a member replaces an identically named member on the old master data 
set or a member is changed and rewritten on the old master, the alias (if any) of 
the original member still refers to the original member. However, if an identical 
alias is specified for the newly written member, the original alias entry in the 
directory is changed to refer to the newly written member. 
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The format of the Function statement is: 

./ [name] {ADD } [LIST=ALL] 
{REPL } 

{CHANGE} [,SEQFLD=dd/] 
{REPRO } 



[,NEW= {PO} 
{PS}] 
[,MEMBER= cccccccc] 
[,COLUMN=dd] 
[,UPDATE=INPLACE] 
[,INHDR= cccccccc] 
[,INTLR= cccccccc] 
[,OUTHDR=cccccccc] 
[,OUTTLR= cccccccc] 
[,TOTAL= (routinename,size)] 
[,NAME= cccccccc] 
[,LEVEL=hh] 
[,SOURCE=x] 
[,SSl=hhhhhhhh\ 

where: 

./ 

is required and must appear in columns 1 and 2. 

name 

specifies an optional name which begins in column 3 and extends no further 
than column 10. 

ADD 

specifies that a member or a data set is to be added to an old master data set. 
If a member is to be added and the member name already exists in the old 
master data set, processing is terminated. If, however, PARM=NEW is specified 
on the EXEC statement, the member is replaced. For a sequential output 
master data set, PARM=NEW must always be specified on the EXEC statement. 
At least one blank must precede and follow ADD. 

REPL 

specifies that a member of a data set is being entered in its entirety as a 
replacement for a sequential data set or for a member of the old master data 
set. The member name must already exist in the old master data set. At least 
one blank must precede and follow REPL. 

CHANGE 

specifies that modifications are to be made to an existing member or data set. 
Use of the CHANGE Function statement without a NUMBER or DELETE Detail 
statement, or a Data statement causes an error condition. At least one blank 
must precede and follow CHANGE. 

REPRO 

specifies that a member or a data set is to be copied in its entirety to a new 
master data set. At least one blank must precede and follow REPRO. 
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LIST=ALL 

specifies that the SYSPRINT data set is to contain the entire updated member 
or data set and the control statements used in its creation. If LIST is omitted, 
the SYSPRINT data set contains modifications and control statements only. If 
update was specified, the entire updated member is listed only when 
renumbering has been done. 

SEQFLD=dd/ 

specifies, in decimal, the starting column (up to column 80) and length (8 or 
less) of sequence numbers within existing logical records and subsequent Data 
statements. Note that the starting column specification (dd) plus the length (/) 
cannot exceed the logical record length (LRECL) plus 1. If SEQFLD is omitted, 
738 is assumed, that is, an eight-byte sequence number beginning in column 
73. Therefore, if existing logical records and subsequent Data statements have 
sequence numbers in columns 73 through 80, this keyword need not be coded. 
In any case, sequence numbers on incoming Data statements and existing 
logical records must be padded to the left with enough zeros to fill the length 
of the sequence field. 

NEW= 

specifies the organization of the old master data set and the organization of 
the updated output. NEW should not be specified unless the organization of the 
new master data set is different from the organization of the old master. Refer 
to Table 13-2 for the use of NEW with NAME and MEMBER. These values can 
be coded: 

PO 

specifies that the old master data set is a sequential data set, and that the 
updated output is to become a member of a partitioned data set. 

PS 

specifies that the old master data set is a partitioned data set, and that a 
member of that data set is to be converted into a sequential data set. 

MEMBER == cccccccc 

specifies a name to be assigned to the member placed in the partitioned data 
set defined by the SYSUT2 DD statement. MEMBER is used only when SYSUTl 
defines a sequential data set, SYSUT2 defines a partitioned data set, and 
NEW=PO is specified. Refer to Table 13-2 for the use of MEMBER with NEW. 

COLUMN==dd 

specifies, in decimal, the starting column of a data field within a logical record 
image. The field extends to the end of the image. Within an existing logical 
record, the data in the defined field is replaced by data from a subsequent 
Data statement. COLUMN is valid only when CHANGE is coded. 

UPDATE=INPLACE 

specifies that the old master data set is to be updated within the space it 
actually occupies. The old master data set must reside on a direct access 
device. UPDATE is valid only when coded with CHANGE. 

INHDR = cccccccc 

specifies the symbolic name of the user routine that handles any user input 
(SYSUTl) header labels. When used with UPDATE, this routine assumes a 
special function. This parameter is valid only when a sequential data set is 
being processed. See "LABEL Statement" for a discussion of this function. 

INTLR = cccccccc 

specifies the symbolic name of the user routine that handles any user input 
(SYSUTl) trailer labels. INTLR is valid only when a sequential data set is being 
processed, but not when UPDATE is coded. 
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OUTHDR=cccccccc 

specifies the symbolic name of the user routine that handles any user output 
(SYSUT2) header labels. OUTHDR is valid only when a sequential data set is 
being processed, but not when UPDATE is coded. 

OUTTLR=cccccccc 

specifies the symbolic name of the user routine that handles any user output 
(SYSUT2) trailer labels. OUTTLR is valid only when a sequential data set is 
being processed, but not when UPDATE is coded. 

TOTAL= 

specifies that exits to a user's routine are to be provided prior to writing each 
record. This parameter is valid only when a sequential data set is being 
processed. These values are coded: 

routinename 

specifies the name of the user's totaling routine. 

size 

specifies the number of bytes required for the user's data. The size should 
not exceed 32K, nor be less than 2 bytes. In addition, the keyword 
OPTCD=T must be specified for the SYSUT2 (output) dd statement. Refer 
to "Appendix A: Exit Routine Linkage" for a discussion of linkage 
conventions for user routines. 

NAME = cccccccc 

indicates the name of the member placed into the partitioned data set. The 
member name need not be specified in the DD statement itself. NAME musi; be 
provided to identify each input member. Refer to Table 13-2 for the use of 
NAME with NEW. This parameter is valid only when a member of a partitioned 
data set is being processed. 

LEVEL=hh 

specifies the change (update) level in hexadecimal (00-FF). The level number 
is recorded in the directory entry of the output member. This parameter is 
valid only when a member of a partitioned data set is being processed. 

SOURCE=x 

specifies user modifications when the x value is 0, or IBM modifications when 
the x value is 1. The source is recorded in the directory entry of the output 
member. This parameter is valid only when a member of a partitioned data set 
is being processed. 

SSl=hhhhhhhh 

specifies eight hexadecimal characters of system status information (SSI) to be 
placed in the directory of the new master data set as four packed hexadecimal 
bytes of user data. This parameter is valid only when a member of a 
partitioned data set is being processed. SSI overrides any LEVEL or SOURCE 
data given on the same Function statement. 

Members can be deleted from a copy of a library by being omitted from a series 
of REPRO Function statements within the same job step. 

One sequential data set can be copied in a given job step. A sequential data set 
is deleted by being omitted from a series of job steps which copy only the 
desired data sets to a new volume. If the NEW subparameter is coded in the 
EXEC statement, only the ADD Function statement is permitted. 

Figure 13-1 shows how the system status information (SSI=0A3C123B) is packed. 
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Change level 
byte 1 


Flag byte 
byte 2 


Serial number 
byte 3 


byte 4 


A 


3 C 


1 2 


3 B 



Figure 13-1. Format of System Status Information 
When UPDATE is specified: 

• The SYSUT2 DD statement is not coded. 

• The PARM parameter of the EXEC statement must imply or specify MOD. 

• The NUMBER statement can be used to specify a renumbering operation. 

• Data statements can be used to specify replacement information only. 

• One CHANGE Function statement and one UPDATE parameter are permitted per 
job step. 

• No functions other than replacement, renumbering, and header label 
modification (via the LABEL statement) can be specified. 

• Only replaced records are listed unless the entire data set is renumbered. 

• System status information cannot be changed. 

Within an existing logical record, the data in the field defined by COLUMN is 
replaced by data from a subsequent data statement, as follows: 

1. IEBUPDTE matches a sequence number of a Data statement with a sequence 
number of an existing logical record. In this manner, the COLUMN 
specification is applied to a specific logical record. 

2. The information in the field within the Data statement replaces the 
information in the field within the existing logical record. For example, 
COLUMN =40 indicates that columns 40 through 80 (assuming 80-byte logical 
records) of a subsequent Data statement are to be used as replacement data 
for columns 40 through 80 of a logical record identified by a matching 
sequence number. (A sequence number in an existing logical record or Data 
statement need not be within the defined field.) 

The COLUMN specification applies to the entire function, with the exception of: 

• Logical records deleted by a subsequent DELETE Detail statement. 

• Subsequent Data statements not having a matching sequence number for an 
existing logical record. 

• Data statements containing information to be inserted in the place of a deleted 
logical record or records. 

Table 13-2 shows the use of NEW, MEMBER, and NAME parameters for different 
input and output data set organizations. 
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Detail Statement 



Table 13-2. new, member, and name Parameters 

Input Data Set Output Data Set Parameter 
Organization Organization Combinations 

Partitioned Partitioned With an ADD Function statement, use NAME to specify 

the name of the member to be placed in the partitioned 
data set defined by the SYSUT2 DD statement. If an 
additional name is required, an ALIAS statement can also 
be used. 

With a change, repl, or repro Function statement, 
use NAME to specify the name of the member within the 
partitioned data set defined by the sysuti*dd statement. 
If a different or additional name is desired for the 
member in the partitioned data set defined by the 
SYSUT2 dd statement, use an alias statement also. 

None Partitioned (New) With each ADD Function statement, use NAME to assign 

a name for each member to be placed in the partitioned 
data set. 

Partitioned Sequential With a Function statement, use NAME to specify the 

name of the member in the partitioned data set defined 
by the SYSUTl DD statement. Use NEW-PS to specify the 
change in organization from partitioned to sequential. 
(The name and file sequence number assigned to the 
output master data set are specified in the SYSUT2 E>D 
statement.) 

Sequential Partitioned With a Function statement, use MEMBER to assign a 

name to the member to be placed in the partitioned data 
set defined by the SYSUT2 DD statement. Use NEW-PO to 
specify the change in organization from sequential to 
partitioned. 

For a detailed discussion of the processing of user labels as data set descriptors, 
and for a discussion of user-label totaling, see "Appendix D: Processing User 
Labels." 



A Detail statement is used with a Function statement for certain applications, 
such as deleting or renumbering selected logical records. 

Note: Logical records cannot be deleted in part; that is, a COLUMN specification 
in a Function statement is not applicable to records that are to be deleted. Each 
specific sequence number is handled only once in any single operation. 

The format of a Detail statement is: 

./[name] {NUMBER} [SEQ1 = {cccccccc} 
{DELETE} {ALL }] 

[,SEQ2= cccccccc] 
[,NEW1 = cccccccc] 
[,INCR = cccccccc] 
[,INSERT=YES] 

where: 

./ 

is required and must appear in columns 1 and 2. 

name 

specifies an optional name which begins in column 3 and extends no further 
than column 10. 

NUMBER 

specifies, when coded with a CHANGE Function statement, that the sequence 
number of one or more logical records is to be changed. It specifies, when 
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coded with an ADD or REPL Function statement, the sequence numbers to be 
assigned to the records within new or replacement members or data sets. 
When used with an ADD or REPL Function statement, no more than one 
NUMBER Detail statement is permitted for each ADD or REPL Function 
statement. If NUMBER is coded, it must be preceded and followed by at least 
one blank. 

DELETE 

specifies, when coded with a CHANGE Function statement, that one or more 
logical records are to be deleted from a member or data set. If DELETE is 
coded, it must be preceded and followed by at least one blank. 

SEQ1 = 

specifies records to be renumbered, deleted, or assigned sequence numbers. 
These values can be coded: 

cccccccc 

specifies the sequence number of the first logical record to be renumbered 
or deleted. This value is not coded in a NUMBER Detail statement that is 
used with an ADD or REPL Function statement. When this value is used in 
an insert operation, it specifies the existing logical record after which an 
insert is to be made. It must not equal the number of a statement just 
replaced or added. Refer to the INSERT parameter for additional discussion. 

ALL 

specifies a renumbering operation for the entire member or data set. ALL is 
used only when a CHANGE Function statement and a NUMBER Detail 
statement are used. ALL must be coded if sequence numbers are to be 
assigned to existing logical records having blank sequence numbers. If ALL 
is not coded, all existing logical records having blank sequence numbers are 
copied directly to the output master data set. When ALL is coded: (1) SEQ2 
need not be coded and (2) one NUMBER Detail statement is permitted per 
Function statement. Refer to the INSERT parameter for additonal discussion. 

SEQ2 = cccccccc 

specifies the sequence number of the last logical record to be renumbered or 
deleted. If only one record is to be deleted, the SEQl and SEQ2 specifications 
must be identical. SEQ2 is not coded in a NUMBER Detail statement that is 
used with an ADD or REPL Function statement. 

NEW 1= cccccccc 

specifies the first sequence number assigned to new or replacement data, or 
specifies the first sequence number assigned in a renumbering operation. A 
value specified in NEWl must be greater than a value specified in SEQl (unless 
SEQl=ALL is specified, in which case this rule does not apply). This parameter 
is valid only in a NUMBER Detail statement. 

INCR= cccccccc 

specifies an increment value used for assigning successive sequence numbers to 
new or replacement logical records, or specifies an increment value used for 
renumbering existing logical records. This parameter is valid only in a NUMBER 
Detail statement. 

INSERT=YES 

specifies the insertion of a block of logical records. The records, which are 
Data statements containing blank sequence numbers, are numbered and 
inserted in the output master data set. INSERT is valid only when coded with 
both a CHANGE Function statement and a NUMBER Detail statement. 
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When INSERT is coded: 

• The SEQ1 parameter specifies the existing logical record after which the 
insertion is to be made. The SEQ2 parameter need not be coded; seqi=all 
cannot be coded. 

• The NEW1 parameter assigns a sequence number to the first logical record to 
be inserted. 

• The INCR parameter is used to renumber as much as is necessary of the 
member or data set from the point of the first insertion; the member or data 
set is renumbered until an existing logical record is found whose sequence 
number is equal to or greater than the next sequence number to be assigned. 
If no such logical record is found, the entire member or data set is 
renumbered. 

• Additional NUMBER Detail statements, if any, must specify INSERT. If a prior 
numbering operation renumbers the logical record specified in the SEQ1 
parameter of a subsequent NUMBER Detail statement, any NEWI or INCR 
parameter specifications in the latter NUMBER statement are overridden. The 
prior increment value is used to assign the next successive sequence numbers. 
If a prior numbering operation does not renumber the logical record specified 
in the SEQI parameter of a subsequent number Detail statement, the latter 
statement must contain NEWl and INCR specifications. 

• The block of Data statements to be inserted must contain blank sequence 
numbers. 

• The insert operation is terminated when a Function statement, a Detail 
statement, an end-of-file indication, or a Data statement containing a sequence 
number is encountered. 

The SEQl, SEQ2, NEWl, and INCR parameters (with the exception of SEQ=ALL) 
specify eight-character (maximum) decimal numbers. Only the significant 
numbers of a value need be coded; for example, SEQl =00000010 can be shortened 
to SEQl = 10. 



A Data Statement is used with a Function statement, or with a Function 
statement and a Detail statement. It contains a logical record used as replacement 
data for an existing logical record, or new data to be incorporated in the output 
master data set. 

Each Data statement contains one logical record, which begins in the first column 
of the Data statement. The length of the logical record is equal to the logical 
record length (LRECL) specified for the output master data set. Each logical 
record contains a sequence number to determine where the data is to be placed 
in the output master data set. 

When used with a CHANGE Function statement, a Data statement contains new 
or replacement data, as follows: 

• If the sequence number in the Data statement is identical with a sequence 
number in an existing logical record, the Data statement replaces the existing 
logical record in the output master data set. 

• If no corresponding sequence number is found within the existing records, the 
Data statement is inserted in the proper collating sequence within the output 
master data set. (For proper execution of this function, all records in the old 
master data set must have a sequence number.) 

• If a Data statement with a sequence number is used and INSERT=YES was 
specified, the insert operation is terminated. IEBUPDTE will continue 
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processing if this sequence number is at least equal to the next old master 
record (record following the referred to sequence record). 

When used with an ADD or REPL Function statement, a Data statement contains 
new data to be placed in the output master data set. 

Sequence numbers within the old master data set are assumed to be in ascending 
order. 

Sequence numbers in Data statements must be in the same relative position as 
sequence numbers in existing logical records. (Sequence numbers are assumed to 
be in columns 73 through 80; if the numbers are in columns other than these, the 
length and relative position must be specified in a SEQFLD parameter within a 
preceding Function statement.) 



The label statement indicates that the following data statements are to be 
treated as user labels. These new user labels are placed on the output data set. 
The next Function statement indicates to IEBUPDTE that the last label Data 
statement of the group has been read. 

The format of the LABEL statement is: 

./[name] LABEL 

where: 



./ 

is required and must appear in columns 1 and 2. 

name 

specifies an optional name which begins in column 3 and extends no further 
than column 10. 

LABEL 

must be preceded and followed by at least one blank. The LABEL statement 
precedes the Data statements which are to be treated as user labels. 

There can be no more than two LABEL statements per execution of IEBUPDTE. 
There can be no more than eight label Data statements following any LABEL 
statement. The first four bytes of each 80-byte label Data statement must 
contain "UHLn" or "UTLn", where n is 1 through 8, for input header or input 
trailer labels respectively, to conform to IBM standards for user labels. Otherwise, 
data management will overlay the data with the proper four characters. 

When IEBUPDTE encounters a LABEL statement, it reads up to eight Data 
statements and saves them for processing by user output label routines. If there 
are no such routines, the saved records are written by OPEN or CLOSE as user 
labels on the output data set. If there are user output label processing routines, 
IEBUPDTE passes a parameter list to the output label routines. This parameter list 
is described fully in ''Appendix A: Exit Routine Linkage." The label buffer 
contains a label data record which the user routine can process before the record 
is written as a label. If the user routine specifies (via return codes to IEBUPDTE) 
more entries than there are label data records, the label buffer will contain 
meaningless information for the remaining entries to the user routine. 

The position of the LABEL statement in the SYSIN data set, relative to Function 
statements, indicates the type of user label that follows the LABEL statement: 

• To create output header labels, place the LABEL statement and its associated 
label Data statements before any Function statements in the input stream. A 
Function statement, other than LABEL, must follow the last label Data 
statement of the group. 
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• To create output trailer labels, place the LABEL statement and its associated 
label Data statements after any Function statements in the input stream, but 
before the ENDUP statement. The ENDUP statement is not optional in this 
case. It must follow the last label Data statement of the group if iEHUPDll. is 
to create output trailer labels. 

When UPDATE is specified in a Function statement, user input header labels can 
be updated by user routines, but input trailer and output labels cannot be 
updated by user routines. User labels cannot be added or deleted. User input 
header labels are made available to user routines by the label buffer address in 
the parameter list. See "Appendix D: Processing User Labels" for a complete 
discussion of the linkage between utility programs and user-label processing 
routines. The return codes when UPDATE is used differ slightly from the standard 
codes discussed in "Appendix D: Processing User Labels," as follows: 

• 0, which specifies that the system resumes normal processing; any additional 
user labels are ignored. 

• 4, which specifies that the system does not write the label. The next user label 
is read into the label buffer area and control is returned to the user's routine. 
If there are no more user labels, the system resumes normal processing. 

• 8, which specifies that the system writes the user labels from the label buffer 
area and resumes normal processing. 

• 12, which specifies that the system writes the user label from the label buffer 
area, then reads the next input label into the label buffer area and returns 
control to the label processing routine. If there are no more user labels, the 
system resumes normal processing. 

If the user wants to examine the replaced labels from the old master data set, he 
must: 

1. Specify an update of the old master by coding the UPDATE parameter in a 
Function statement. 

2. Include a LABEL statement in the input data set for either header or trailer 
labels. 

3. Specify a corresponding user label routine. 

If the above conditions are met, fourth and fifth parameter words will be added 
to the standard parameter list. The fourth parameter word is not now used; the 
fifth contains a pointer to the replaced label from the old master. In this case, 
the number of labels supplied in the SYSIN data set must not exceed the number 
of labels on the old master data set. If the user specifies, via return codes, more 
entries to the user's header label routine than there are labels in the input stream, 
the first parameter will point to the current header label on the old master data 
set for the remaining entries. In this case, the fifth parameter is meaningless. 



The ALIAS statement is used to create or retain an alias in an output 
(partitioned) master directory. The ALIAS statement can be used with any of the 
Function statements. Multiple aliases can be assigned to each member. 

The format of the ALIAS statement is: 

./[name] ALIAS NAME=cccccccc 

where: 

./ 

is required and must appear in columns 1 and 2. 
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name 

specifies an optional name which begins in column 3 and extends no further 
than column 10. 

NAME = cccccccc 

specifies a one- to eight-character alias. 

ALIAS must be preceded and followed by at least one blank. If multiple ALIAS 
statements are used, they must follow the data records. 



An ENDUP statement can be used to indicate the end of SYSIN input to this job 
step. It serves as an end-of-data indication if there is no other indication. The 
ENDUP statement follows the last group of SYSIN control statements. 

The format of the endup statement is: 



./[name] 
where: 
./ 



ENDUP 



is required and must appear in columns 1 and 2. 



name 

specifies an optional name which begins in column 3 and extends no further 
than column 10. 

ENDUP must be preceded and followed by at least one blank. The ENDUP 
statement must follow the last label Data statement if IEBUPDTE is used to create 
output trailer labels. 



The following examples illustrate some of the uses of IEBUPDTE. Table 13-3 can 
be used as a quick reference guide to IEBUPDTE examples. The numbers in the 
"Example" column point to examples that follow. 
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Table 13-3. iebupdte Example Directory 



Data Set 
Operation Organization Device 

CATALOG a Partitioned 2314 Disks 
procedure 



CREATE a Partitioned 2314 Disk 

partitioned 

library 

CREATE a Partitioned 2314 Disk 

partitioned 

data set 

UDPATE Partitioned 2314 Disk 

INPLACE and 

renumber 

CREATE and Partitioned, 3330 Disk, 
DELETE Sequential 9-track Tape 



CREATE, Sequential, 9-track Tape, 

DELETE, and Partitioned 2314 Disk 
UPDATE 



INSERT Partitioned 2314 Disks 



INSERT Partitioned 2314 Disks 



CREATE Sequential Card Reader, 

2314 Disk 

COPY Sequential 2314 Disks 



CREATE Partitioned 2314 Disks 



Comments Example 

SYSUTl and SYSUT2 DD statements 
define the same data set. Procedure 
to be cataloged is in the control 
data set. 1 

Input data is in the control data set. 
Output partitioned data set is to 
contain three members. 2 

Input from control data set and from 
existing partitioned data set. Output 
partitioned data set is to contain four 
members. 3 

Input data set is considered to be the 
output data set as well; therefore, no 
SYSUT2 dd statement is required. 4 

Sequential master is to be created from 
partitioned tape input. Selected 
records are to be deleted. Blocked 
output. 5 

Partitioned data set is to be created 
from sequential input. Records are to 
be deleted and updated. Sequence 
numbers in columns other than 73 
through 80. One member is to be 
placed in the output data set. 6 

Block of logical records is to be 
inserted into an existing member. 
SYSUTl and SYSUT2 DD statements 
define the same data set. 7 

Two blocks of logical records are to be 
inserted into an existing member. 
SYSUTl and SYSUT2 DD statements 
define the same data set. 8 

Sequential data set with user labels is 
to be created from card input. 9 

Sequential data set is to be copied 
from one direct access volume to 
another; user labels can be processed 
by exit routines. 10 

Create a new generation. 1 1 
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In this example, a procedure is to be placed in the cataloged procedure library, 
SYS1.PROCLIB. The example assumes that the new procedure (ERASE) can be 
accommodated within the space originally allocated to the procedure library; 
therefore, the update operation is performed directly to the old master. 

The example follows: 

//UPDATE JOB 09#660, SMITH 

// EXEC PGM=IEBUPDTE,PARM=MOD 

//SYSPRINT DD SYS0UT=A 

DSNAME=SYS1 . PROCLIB,DISP=SHR 

DSNAME=SYS1 . PROCLIB,DISP=SHR 

DATA 

LIST=ALL , NAME=ERASE , LEVEL=0 1 , SOURCE=0 

NEW1=10,INCR=10 
EXEC PGM=IEHPROGM 
DD UNIT=190,DISP=(OLD,KEEP),VOLUME=SER=1 11111 



//SYSUT1 DD 

//SYSUT2 DD 

//SYSIN DD 

./ ADD 
. / NUMBER 
//ERASE 
//DD1 



//SYSPRINT DD 
. / ENDUP 
/* 



SYSOUT=A 
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The control statements are discussed below: 

• sysui I and SYSUT2 DD define the sysi.proclib data set, which is assumed 
to be cataloged. 

• sysin Di) defines the control data set. The data set contains the utility control 
statements and the data to be placed in the procedure library. 

• The ADD Function statement indicates that records (Data statements) in the 
control data set are to be placed in the output. The newly created procedure is 
to be listed in the message data set. 

• The number Detail statement indicates that the new procedure is assigned 
sequence numbers. The first record of the procedure is assigned sequence 
number 10; the remaining two records are assigned sequence numbers 20 and 
30. 

The ERASE EXEC, DD1, and SYSPRINT DD statements are placed in the cataloged 
procedure library, SYSI.PROCLIB, as a result of this job. 

Note: The resulting procedure can be executed with an EXEC statement 
specifying PROC=ERASE. For additional information on cataloged procedures, see 
OS/VS JCL Reference, GC28-0618. 



In this example, a three member, partitioned library is to be created. The input 
data is contained solely in the control data set. 

The example follows: 

//UPDATE JOB 09# 770, SMITH 

// EXEC PGM=IEBUPDTE,PARM=NEW 

//SYSPRINT DD SYSOUT=A 

//SYSUT2 DD DSNAME=OUTLIB,UNIT=2314,DISP=(NEW,KEEP), 

// VOLUME=SER=1 1 1 1 1 2 , SPACE=( TRK, ( 50, , 10 ) ) , DCB=( RECFM=F, 

// LRECL=80,.BLKSIZE=80) 

//SYSIN DD DATA 

./ ADD NAME=MEMB1 ,LEVEL=00,SOURCE=0,LIST=ALL 

(Data statements, sequence numbers in columns 73 through 80) 

./ ADD NAME=MEMB2,LEVEL=00,SOURCE=0,LIST=ALL 

(Data statements, sequence numbers in columns 73 through 80) 

./ ADD NAME=MEMB3,LEVEL=00,SOURCE=0,LIST=AL'L 

(Data statements, sequence numbers in columns 73 through 80) 

. / ENDUP 

/* 

The control statements are discussed below: 

• SYSUT2 DD defines the new partitioned master OUTLIB. Enough space is 
allocated to allow for subsequent modifications without creating a new master 
data set. 

• SYSIN DD defines the control data set. The data set contains the utility control 
statements and the data to be placed as three members in the output 
partitioned data set. 

• The ADD Function statements indicate that subsequent Data statements are to 
be placed as members in the output partitioned data set. Each ADD Function 
statement specifies a member name for subsequent data and indicates that the 
member is to be listed in the message data set. 

• The Data statements contain the data to be placed in the output partitioned 
data set. 
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• ENDUP signals the end of control data set input. 

Note: Because sequence numbers (other than blank numbers) are included within 
the Data statements, no NUMBER Detail statements are included in the example. 



In this example, a four-member, partitioned data set (NEWMCLIB) is to be 
created. The data set is to contain: 

• Two members (ATTACH and DETACH) copied from an existing partitioned 
data set (SYS1.MACLIB). 

• One replacement member (BLDL) for an existing member of the input 
partitioned data set. 

• A new member (EXIT), which is contained in the control data set. 

The example follows: 

//UPDATE JOB 09#770, SMITH 

// EXEC PGM=IEBUPDTE,PARM=MOD 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=SYS1 .MACLIB, DISP=SHR, UNIT=23 1 4 

//SYSUT2 DD DSNAME=NEWMCLIB,V0LUME=SER=1 1 1 1 12,UNIT=2314, 

// DISP=( NEW, KEEP ) , SPACE=( TRK, ( 100, , 10 ) ) , DCB=( RECFM=F, 

// LRECL=80,BLKSIZE=80 ) 

//SYSIN DD DATA 

./ REPRO NAME-ATTACH, LEVEL=00, SOURCE= 1 ,LIST=ALL 

./ REPRO NAME-DETACH, LEVEL=00, SOURCE- 1 , LI ST=ALL 

./ ADD NAME-EXIT, LEVEL=00, SOURCE= 1 ,LIST=ALL 

./ NUMBER NEW1=10,INCR=100 

(Data cards for EXIT member) 

./ REPL NAME=BLDL,LEVEL=01 ,SOURCE=1 ,LIST=ALL 
./ NUMBER NEW1-10,INCR=100 

(Data cards to replace BLDL member) 

. / ENDUP 

/* 

The control statements are discussed below: 

• SYSUTl DD defines the input partitioned data set SYSl. MACLIB, which is 
assumed to be cataloged. 

• SYSUT2 DD defines the output partitioned data set OUTLIB. Enough space is 
allocated to allow for subsequent modifications without creating a new master 
data set. 

• SYSIN DD defines the control data set. 

• The REPRO Function statements identify the existing input members to be 
copied onto the output data set. These members are also listed in the message 
data set. 

• The ADD Function statement indicates that records (subsequent Data 
statements) are to be placed as a member in the output partitioned data set. 
The Data statements are to be listed in the message data set. 

• The NUMBER Detail statement assigns sequence numbers to the Data 
statements. (The Data statements contain blank sequence numbers in columns 
73 through 80.) The first record of the output member is assigned sequence 
number 10; subsequent records are incremented by 100. 

• The REPL Function statement identifies a new member used as a replacement 
for an existing member. The subsequent NUMBER Detail statement assigns 
sequence numbers to the records in the new member. 
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IEBUPDTE Example 5 



• ENDUP signals the end of SYSIN data. 

Note: The three named input members (ATTACH, DETACH, and BLDL) do not 
have to be specified in the order of their collating sequence in the old master. 



In this example, a member (MODMEMB) is to be updated within the space it 
actually occupies. Two existing logical records are to be replaced, and the entire 
member is to be renumbered. 

The example follows: 

//UPDATE JOB 09#770, SMITH 

// EXEC PGM=IEBUPDTE,PARM=MOD 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=PDS,UNIT=2314,DISP=(OLD,KEEP), 

// VOLUME=SER= 111112, DCB=( RECFM=F , LRECL=80 , BLKSIZE=80 ) 

//SYSIN DD * 

./ CHANGE NAME=MODMEMB,LIST=ALL,UPDATE=INPLACE 

./ NUMBER SEQ1=ALL,NEW1=10,INCR=5 

(Data statement 1, sequence number 00000020) 
(Data statement 2, sequence number 00000035) 

/* 

The control statements are discussed below: 

• SYSUTl DD defines the data set that is to be updated in place. (Note that the 
member name need not be specified in the DD statement.) 

• SYSIN DD defines the control data set. 

• The CHANGE Function statement indicates the name of the member to be 
updated and specifies the UPDATE=INPLACE operation. The entire member is 
to be listed in the message data set. 

• The NUMBER Detail statement indicates that the entire member is to be 
renumbered, and specifies the first sequence number to be assigned and the 
increment value for successive sequence numbers. 

• The Data statements replace existing logical records having sequence numbers 
of 20 and 35. 



In this example, a sequential master data set is to be created from partitioned 
input and selected logical records are to be deleted. 

The example follows: 

//UPDATE JOB 09#770, SMITH 

// EXEC PGM=IEBUPDTE,PARM=MOD 

//SYSPRINT DD SYSOUT=A 

//SYSUTl DD DSNAME=PARTDS,UNIT=3330,DISP=( OLD, KEEP), 

// VOLUME=SER=1 11112 

//SYSUT2 DD DSNAME=SEQDS,UNIT=2400,LABEL=( 2 , SL ) , 

// DISP=( , KEEP ),VOLUME=SER=001 234, DCB=( RECFM=FB, 

// LRECL=80,BLKSIZE=2000 ) 

//SYSIN DD * 

. / CHANGE NEW=PS , NAME=OLDMEMB 1 

(Data statement 1, sequence number 00000123) 

./ DELETE SEQ1=223,SEQ2=246 

(Data statement 2, sequence number 00000224) 
/* 
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The control statements are discussed below: 

• SYSUTl DD defines the input partitioned data set partds. Because no DCB 
parameters are specified in the SYSUTl DD statement, the input data set is 
assumed to consist of 80-byte, unblocked records. A warning message is issued 
to inform the user that this assumption was made. 

• SYSUT2 DD defines the output sequential data set. The data set is to be 
written as the second data set on a 9-track tape volume. The data set is 
written at a density of 800 bits per inch. 

• SYSIN DD defines the control data set. 

• CHANGE identifies the input member (OLDMEMBl) and indicates that the 
output is to be a sequential data set (NEW=PS). 

• The first Data statement replaces the logical record whose sequence number is 
identical to the sequence number in the Data statement (00000123). If no 
such logical record exists, the Data statement is incorporated in the proper 
sequence within the output data set. 

• The DELETE Detail statement deletes logical records having sequence numbers 
from 223 through 246. 

• The second Data statement is inserted in the proper sequence in the output 
data set. 

Note: Only one member can be used as input when converting to sequential 
organization. 



In this example, a member of a partitioned data set is to be created from 
sequential input and existing logical records are to be updated. 

The example follows: 

72 
//UPDATE JOB 09#770, SMITH 
// EXEC PGM=IEBUPDTE,PARM=MOD 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=OLDSEQDS,UNIT=2400,LABEL=( ,SL), 
// DISP=( OLD , KEEP ) , VOLUME=SER=00 1234, DCB=( RECFM=F , 
// LRECL=80,BLKSIZE=80 ) 

//SYSUT2 DD DSNAME=NEWPART,UNIT=2314,DISP=( ,KEEP), 
// VOLUME=SER=1 1 1 1 1 2 , SPACE=( TRK, ( 10,5,5 ) ), 
// DCB=( RECFM-F , LRECL=80 , BLKSIZE=80 ) 
//SYSIN DD * 

./ CHANGE NEW=PO,MEMBER=PARMEM1 ,LEVEL=01 , C 

./ SEQFLD=605,COLUMN=40,SOURCE=0 

(Data statement 1 , sequence number 00020) 

./ DELETE SEQ1=220,SEQ2=250 

(Data statement 2, sequence number 00230) 
(Data statement 3, sequence number 00260) 

./ ALIAS NAME=MEMB1 

/* 

The control statements are discussed below: 

• SYSUTl DD defines the input sequential data set (OLDSEQDS). The data set 
was originally written at a density of 800 bits per inch on a 9-track tape 
volume. 

• SYSUT2 DD defines the output partitioned data set. Enough space is allocated 
to provide for members that might be added in subsequent job steps. 
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• SYSIN DD defines the control data set. 

• The CHANGE Function statement identifies the output member and indicates 
that a conversion from sequential input to partitioned output is to be made. 
The SEQFLD parameter indicates that a five-byte sequence number is located 
in columns 60 through 64 of each Data statement. The COLUMN parameter 
specifies the starting column of a field (within subsequent Data statements) 
from which replacement information is obtained. 

• The first Data statement is used as replacement data. Columns 40 through 80 
of the statement replace columns 40 through 80 of the corresponding logical 
record. If no such logical record exists, the entire card image is inserted in the 
output member. 

• The DELETE Detail statement deletes all of the logical records having sequence 
numbers from 220 through 250. 

• The second Data statement, whose sequence number falls within the range 
specified in the DELETE Detail statement, is incorporated in its entirety in the 
output member. 

• The third Data statement, which is beyond the range of the DELETE Detail 
statement, is treated in the same manner as the first Data statement. 

• alias assigns the alias MEMBl to the output member parmemi. 



In this example, a block of three logical records is to be inserted into an existing 
member, and the updated member is to be placed in the existing partitioned data 
set. 

Figure 13-2 shows existing sequence numbers, new sequence numbers, and Data 
statements to be inserted. 



Sequence Numbers and 
Data Statements to be 
Inserted 

10 

15 

Data statement 1 

Data statement 2 

Data statement 3 

20 

25 

30 



New Sequence Numbers 

10 
15 
20 

25 
30 
35 
40 
45 



Figure 13-2. Sequence Numbers and Data Statements to be Inserted 

The example follows: 

//UPDATE JOB 09#770, SMITH 

// EXEC PGM=IEBUPDTE,PARM=MOD 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=PDS,UNIT=2314,DISP=(OLD,KEEP), 

// VOLUME=SER=1 11112, 

// DCB=( RECFM=F , LRECL=80 , BLKSIZE=80 ) 

//SYSUT2 DD DSNAME=PDS,UNIT=2314,DISP=(OLD,KEEP), 

// VOLUME=SER=1 1 1 1 1 2 ,DCB=( RECFM=F, LRECL=80 , BLKSIZE=80 ) 

//SYSIN DD * 

./ CHANGE NAME=RENUM,LIST=ALL,LEVEL=01 , SOURCE=0 

./ NUMBER SEQ1=15,NEW1=20,INCR=5,INSERT=YES 

(Data statement 1) 
(Data statement 2) 
(Data statement 3) 

/* 
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The control statements are discussed below: 

• SYSUTl and SYSUT2 DD define the partitioned data set (PDS). 

• SYSIN DD defines the control data set. 

• The CHANGE Function statement identifies the input member RENUM. The 
entire member is to be listed in the message data set. 

• The NUMBER Detail statement specifies the insert operation and controls the 
renumbering operation. 

• The Data statements are the logical records to be inserted. (Sequence numbers 
are assigned when the Data statements are inserted.) 

In this example, the existing logical records have sequence numbers 10, 15, 20, 
25, 30, etc. Sequence numbers are assigned by the NUMBER Detail statement, as 
follows: 

1. Data statement 1 is assigned sequence number 20 (NEW 1=20) and inserted 
after existing logical record 15 (SEQ1 = 15). 

2. Data statements 2 and 3 are assigned sequence numbers 25 and 30 (INCR==5) 
and are inserted after Data statement 1. 

3. Existing logical records 20, 25, and 30 are assigned sequence numbers 35, 40, 
and 45, respectively. 

4. The remaining logical records in the member are renumbered. 



In this example, two blocks (three logical records per block) are to be inserted 
into an existing member, and the member is to be placed in the existing 
partitioned data set. A portion of the output member is to be renumbered. 

Figure 13-3 shows existing sequence numbers, new sequence numbers, and Data 
statements to be inserted. 

Sequence Numbers and 
Data Statements to be 
Inserted New Sequence Numbers 

10 10 

15 15 

Data statement 1 20 

Data statement 2 25 

Data statement 3 30 

20 35 

25 40 

30 45 

Data statement 4 50 

Data statement 5 55 

Data statement 6 60 

35 65 

Data statement 7 70 

40 75 

50 80 

150 150 

155 155 

Figure 13-3. Sequence Numbers and Seven Data Statements to be Inserted 
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The example follows: 

//UPDATE JOB 09#770, SMITH 

// EXEC PGM=IEBUPDTE,PARM=MOD 

//SYSPRINT DD SYSOUT-A 

//SYSUT1 DD DSNAME=PDS,UNIT=2314,DISP=(OLD,KEEP), 

// VOLUME=SER=1 11112, 

//SYSUT2 DD DSNAME=PDS,UNIT=2314,DISP=(OLD,KEEP), 

// VOLUME=SER=1 11112, 

//SYSIN DD * 

./ CHANGE NAME=RENUM,LIST=ALL,LEVEL=01 , SOURCE=0 

./ NUMBER SEQ1=15,NEW1=20,INCR=5,INSERT=YES 

(Data statement 1 ) 
(Data statement 2) 
(Data statement 3) 



/ 



NUMBER SEQ1=30,INSERT=YES 



(Data statement 4) 
(Data statement 5) 
(Data statement 6) 
(Data statement 7, sequence number 00000038) 

/* 

The control statements are discussed below: 

• sysuti and SYSUT2 dd define the partitioned data set pds. 

• SYSIN DD defines the control data set. 

• The CHANGE Function statement identifies the input member RENUM. The 
entire member is to be listed in the message data set. 

• The NUMBER Detail statements specify the insert operations (INSERT=YES) 
and control the renumbering operation. 

• Data statements 1, 2, 3, and 4, 5, 6 are the blocks of logical records to be 
inserted. Because they contain blank sequence numbers, sequence numbers are 
assigned when the Data statements are inserted. 

• Data statement 7 is a logical record to be inserted in the output member. 

The existing logical records in this example have sequence numbers 10, 15, 20, 
25, 30, 35, 40, 45, 50, 150, 155, 160, 165, etc. The insert and renumbering 
operations are performed as follows: 

1. Data statement 1 is assigned sequence number 20 (new 1=20) and inserted 
after existing logical record 15 (SEQ1=15). 

2. Data statements 2 and 3 are assigned sequence numbers 25 and 30 (INCR=5) 
and are inserted after Data statement 1. 

3. Existing logical records 20, 25, and 30 are assigned sequence numbers 35, 40, 
and 45, respectively. 

4. Data statement 4 is assigned sequence number 50 and inserted. (The SEQ1=30 
specification in the second NUMBER statement places this Data statement after 
existing logical record 30, which has become logical record 45.) 

5. Data statements 5 and 6 are assigned sequence numbers 55 and 60 and are 
inserted after Data statement 4. 

6. Existing logical record 35 is assigned sequence number 65. 

7. Data statement 7 is assigned sequence number 70 and is inserted. 

8. The remaining logical records in the member are renumbered until logical 
record 150 is encountered. Because this record has a sequence number higher 
than the next number to be assigned, the renumbering operation is terminated. 
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IEBUPDTE Example 10 



In this example, IEBUPDTE is used to create a sequential data set from card 
input. User header and trailer labels, also from the input stream, are placed on 
this sequential data set. 

The example follows: 

//LABEL JOB ,MSGLEVEL=1 

//CREATION EXEC PGM=IEBUPDTE ,PARM=NEW 

//SYSPRINT DD SYSOUT=A 

//SYSUT2 DD DSNAME-LABEL,VOLUME=SER=12 3456,UNIT=2314, 

// DISP=( NEW, KEEP ),LABEL=( , SUL ) , SPACE=( TRK, ( 15,3 ) ) 

//SYSIN DD * 

. / LABEL 

(First header label) 

(Last header label) 

./ ADD LIST=ALL,0UTHDR=R0UTINE1 ,0UTTLR=R0UTINE2 

(First input data record) 
(Last input data record) 

. / LABEL 

(First trailer label) 
(Last trailer label) 



• / 
/* 



ENDUP 



The control statements are discussed below: 

• SYSUT2 DD defines and allocates space for the output sequential data set, 
which resides on a 2314 volume. 

• SYSIN DD defines the control data set. (This control data set includes the 
sequential input data set and the user labels, which are on cards.) 

• The first LABEL statement identifies the 80-byte card images in the input 
stream which will become user header labels. (They can be modified by the 
user's header-label processing routine specified on the ADD Function 
statement.) 

• The ADD Function statement indicates that the Data statements that follow are 
to be placed in the output data set. The newly created data set is to be listed 
in the message data set. User output header and output trailer routines are to 
be given control prior to the writing of header and trailer labels. 

• The second LABEL statement identifies the 80-byte card images in the input 
stream which will become user trailer labels. (They can be modified by the 
user's trailer-label processing routine specified on the ADD Function 
statement.) 

• ENDUP signals the end of the control data set. 



In this example, IEBUPDTE is used to copy a sequential data set from one direct 
access volume to another. User labels are processed by user exit routines. 
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The example follows: 



IEBUPDTE Example 11 



72 



//LABELS JOB ,MSGLEVEL=1 

// EXEC PGM=IEBUPDTE,PARM=(MOD, ,MMMMMM) 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=OLDMAST , DISP=OLD, LABEL- ( , SUL ) , 

// VOLUME=SER=1 11111 ,UNIT=2314 

//SYSUT2 DD DSNAME=NEWMAST,DISP=( NEW, KEEP ),LABEL=( , SUL), 

// UNIT=2314,VOLUME=SER=XB182,SPACE=(TRK,( 5,10)) 

//SYSIN DD DSNAME=INPUT,DISP=OLD,LABEL=( , SUL ) , 

// VOLUME=SER=222222,UNIT=2314 

/* 



(Input data set) 

REPRO 



• / 

• / 

• / 
/* 



LIST=ALL,INHDR=SSSSSS,INTLR=TTTTTT, 
OUTHDR=XXXXXX , OUTTLR=YYYYYY 



ENDUP 



The control statements are discussed below: 

• SYSUTl DD defines the input sequential data set, which resides on a 2314 
volume. 

• SYSUT2 DD defines the output sequential data set, which will reside on a 2314 
volume. 

• SYSIN DD defines the control data set. 

• The REPRO Function statement indicates that the existing input sequential data 
set is to be copied to the output data set. This output data set is to be listed 
on the message data set. The user's label processing routines are to be given 
control when header or trailer labels are encountered on either the input or 
the output data set. 

• ENDUP indicates the end of the control data set. 



In this example, a partitioned generation consisting of three members is to be 
used as source data in the creation of a new generation. IEBUPDTE is to be used 
to add a fourth member to the three source members and to number the new 
member. The resultant data set is to be cataloged as a new generation. 

The example follows: 

// JOB 

// EXEC PGM=IEBUPDTE,PARM=MOD 

//SYSPRINT DD SYSOUT-A 

//SYSUT1 DD DSNAME=A.B.C( ),DISP=OLD 

//SYSUT2 DD DSNAME=A.B.C(+1 ),DISP=( , CATLG ) , UNIT=23 1 4 , 

// VOLUME=SER=23 1 400 , SPACE=( TRK, (100,10,10)), 

// DCB=(RECFM=FB,LRECL=80,BLKSIZE=800 ) 



//SYSIN 

• / 

• / 
■ / 

• / 

• / 



REPRO 

REPRO 

REPRO 

ADD 

NUMBER 



DD DATA 

NAME=MEM1 , LEVEL=00 , SOURCE=0 , LIST=ALL 
NAME=MEM2 , LEVEL=00 , SOURCE=0 , LIST=ALL 
NAME=MEM3 , LEVEL=00 , SOURCE=0 , LIST=ALL 
NAME=MEM4 , LEVEL=00 , SOURCE=0 , LIST=ALL 
NEW1=10,INCR=5 



(data cards comprising MEM4) 

./ ENDUP 
/* 

The control statements are discussed below: 

• SYSUTl DD defines the latest generation, which is used as source data. 
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• SYSUT2 DD defines the new generation, which is created from the source 
generation and from an additional member included as input and data. 

• The REPRO Function statements reproduce the named source members in the 
output generation. 

• The ADD Function statement specifies that the data cards following the input 
stream be included as MEM4. 

• The NUMBER Detail statement indicates that the new member is to have 
sequence numbers assigned in columns 73 through 80. The first record is 
assigned sequence number 10. The sequence number of each successive record 
is incremented by 5. 

• ENDUP signals the end of input card data. 

Note: This example assumes that a model DSCB exists on the catalog volume on 
which the index was built. 
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I EH ATLAS Program 



Input and Output 



IEHATLAS is a system utility used when a defective track is indicated by a data 
check or missing address marker condition. (See "Introduction" for general 
system utility information.) 

IEHATLAS can be used to locate and assign an alternate track to replace the 
defective track. Usable data records on the defective track are retrieved and 
transferred to the alternate track. A replacement for the bad record is created 
from data supplied by the user and placed on the alternate track. 

In a simple application, IEHATLAS is used as a separate job after an abnormal 
termination of a problem program. Input data necessary for execution of 
IEHATLAS — the address of the defective track and replacement records — may be 
obtained from the dump and from backup data. 

A more complex use of IEHATLAS may involve the preparation of a user's 
SYNAD routine, which reconstructs the necessary input data and invokes 
IEHATLAS dynamically. 

When IEHATLAS is invoked, it attempts to write on the defective track. If the 
subsequent read-back check indicates that the attempt was successful, a message 
is issued on the SYSOUT device. If not, a supervisor call routine (SVC 86) is 
entered automatically. 

The SVC routine locates and assigns an alternate track. (If a defective track 
already has an alternate and an error occurs on that alternate, the SVC routine 
assigns the next available alternate. All of the valid data records on the defective 
track are retrieved and transferred to the alternate track. The input record is 
written on the alternate track in the correct position to recover from the previous 
error. 

When a READ error occurs and a complete recovery is desired, IEHDASDR can be 
used to produce a listing of error data on a track. Using this data, the input data 
record for IEHATLAS can be created. The replace function can then be performed 
by executing IEHATLAS. 

The direct access device types supported by IEHATLAS are the 2305, 2314, 2319, 
3330, 3330-1, and 3340. 



IEHATLAS uses the following input: (1) a description of the defective track, 
specifying the cylinder, track, record, key, and data length (in hexadecimal 
notation), (2) an indication if WRITE Special is needed, and (3) a valid copy (in 
hexadecimal notation) of the bad record. 

IEHATLAS produces as output: (1) a message, issued on the SYSOUT device, 
containing the user's control information, the input record, and diagnostics, (2) 
the input record, written on either the original (defective) track or on an 
alternate track containing the usable data taken from the defective track, and (3) 
the return parameter list (specifying a maximum of three error record numbers in 
hexadecimal when an unrecoverable error occurs). 
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Control 

IEHATLAS is controlled by job control statements and utility control statements. 
The job control statements are used to execute or invoke IEHATLAS and to 
define the data sets used and produced by IEHATLAS. 

A utility control statement is used to specify whether the bad record is a member 
of the volume table of contents or a member of some other data set. It is also 
used to indicate whether or not the WRITE Special command is to be used. 

Job Control Statements 

Table 14-1 shows the job control statements necessary for using IEHATLAS. 

Table 14-1. ieh atlas Job Control Statements 

Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (PGM =IEH ATLAS) or, if the job control statements 

reside in a procedure library, the procedure name. 

S YSPRINT DD Defines a sequential data set that contains the output messages issued by 
IEHATLAS. 

SYSUT1 DD Defines the data set that contains the bad record. 

SYSIN DD Defines the control data set, which contains the utility control statement and a 
copy of the bad record. 



Restrictions 

• The block size for the S YSPRINT data set must be a multiple of 121. The 
block size for the SYSIN data set must be a multiple of 80. Any blocking 
factor can be specified. 

• DISP=SHR must not be coded on the SYSUTl DD statement. 

Utility Control Statement 

The TRACK or VTOC control statement is used to control IEHATLAS. 

TRACK or VTOC Statement 

The TRACK or VTOC statement is used to identify the defective record. 

The format of the TRACK or VTOC statement is: 

{TRACK =bbbbcccchhhhrrkkdddd[S] } 
{VTOC= bbbbcccchhhhrrkkdddd } 

where: 

TRACK= 

specifies that an alternate track is to be assigned for a track that does not 
contain VTOC records. 

VTOC= 

specifies that an alternate track is to be assigned for a track that contains 
VTOC records. 

bbbb 

This number must be padded with zeros. 

cccc 

is the number of the cylinder in which the defective track was found. 

hhhh 

is the defective track number. 
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rrkk 



is the record number and key length for the bad record. 

dddd 

is the data length of the bad record. (When a WRITE Special command is 
used, dddd is the length of the record segment.) 

S 

is an optional byte of EBCDIC information that specifies that the WRITE 
Special command is to be used (when the last record on the track overflows 
and must be completed elsewhere). 

Care should be taken to ensure that the input record data length does not exceed 
the track size. This is especially important when the WRITE Special command is 
specified because the error may not be recognized immediately by the system. 

The TRACK or VTOC statement must not begin in column 1. 

Input data (consisting of the hexadecimal replacement record) begins in column 1 
immediately following the utility control data. Input data may continue through 
column 80. As many cards as necessary may be used to contain the replacement 
record. All columns (1 through 80) are used on the additional cards. 

IEHATLAS is designed to replace an error record with a copy of that record. It 
cannot be used to replace a record with another of a different key and/or data 
length. 

An end-of-file record cannot be changed; therefore, input for key and/or data 
fields are ignored. 



IEHATLAS Examples 



IEHATLAS Example 1 



The following examples illustrate some of the uses of IEHATLAS. Table 14-2 can 
be used as a quick reference guide to IEHATLAS examples. The numbers in the 
"Example" column point to examples that follow. 



Table 14-2. 


iehatlas Example Directory 




Operation 


Comments 


Example 


Get Alternate 
Track 


Write Special is included because of a 
track overflow condition. 


1 


Get Alternate 
Track 


Alternate track assigned for a bad 
end-of-file record. 


2 


Get Alternate 
Track 


Alternate track assigned for a bad 
VTOC record. 


3 


Get Alternate 
Track 


Replace defective record zero. 


4 



In this example, the data set defined by SYSUTl contains the bad record. An 
alternate track on the specified unit and volume will be assigned to replace the 
defective track. 

The example follows: 

//JOBATLAS JOB 06#990 , SMITH, MSGLEVEL=1 

//STEP EXEC PGM=IEHATLAS 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=NEWSET,UNIT=3330,VOLUME=SER=33301 1 , 

// DISP=OLD 

//SYSIN DD * 

TRACK=00000002000422020006S 
F3F1C2C2F0F00000 
/* 
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I EH ATLAS Example 2 



The control statements are discussed below: 

• SYSPRINT DD defines the device to which the output messages can be written. 

• SYSUTl DD defines the data set that contains the bad record. The devices 
supported are 2305, 2314, 2319, 3330, 3330-1, and 3340. 

• sysin DD defines the control data set, which follows in the input stream. 

• TRACK specifies the cylinder and track number for the defective track, and the 
record number, key length, and data length of the bad record. In this example, 
the input record is to be placed on cylinder two, track four, record 22; and it 
has a key length of two with a logical record length of six. The write Special 
(S) character is used because there is a track overflow condition. 

The input record in this example is a typical hexadecimal record as defined by a 
TRACK statement. The input record contains eight bytes (data length = 6, key 
length = 2). 



In this example, an alternate track is assigned for a bad end-of-file record. 

The example follows: 

//JOBATLAS JOB 06#990 , SMITH, MSGLEVEL=1 

//STEP EXEC PGM=IEHATLAS 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=EOFSET,UNIT=2305,VOLUME=SER=33333, 

// DISP-OLD 

//SYSIN DD * 

TRACK=00000001 000003000000 
/* 

The control statements are discussed below: 

• SYSPRINT DD defines the device to which the output messages can be written. 

• SYSUTl DD defines the data set that contains the bad record. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• TRACK defines an end-of-file record on cylinder one, track zero, record three. 
Input data other than the utility control statement is not required. 



I EH ATLAS Example 3 



In this example, an alternate track is assigned for a bad volume table of contents 
record. 

The example follows: 



//JOBTALAS JOB 06# 990 , SMITH ,MSGLEVEL=1 



'/STEP 



EXEC PGM=IEHATLAS 



//SYSPRINT DD SYSOUT=A 
//SYSUT1 



DD 
DD 



UNIT=2314,VOLUME=SER=22222,DISP=OLD 



//SYSIN 

VTOC=000000000005022C0060 
D6C2D1C5C3E340404040404040404040404040404040404040404040404040404040404040404040 
40404040F1F2F3F1F1F0F0000 1440 1360000000 10000000000000000000000000000000000000000 
000040008000000FOOOF00033333333333333333310DDD00000100000AOOOOOOOAOOOOOOOOOOOOOO 
0000000000000000000000000000000000000000 

/* 

The control statements are discussed below: 

• SYSPRINT DD defines the device to which the output messages can be written. 

• SYSUTl DD defines the data set that contains the bad record. 
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I EH ATLAS Example 4 



• SYSIN DD defines the control data set, which follows in the input stream. 

• VTOC defines the location of the bad VTOC record as track five of cylinder 
zero. The record number is 2 with a key length of 44. Record length of the 
bad record is 96. 

The input record in this example is a typical hexadecimal record as defined by 
the VTOC statement. The input record contains 140 bytes (data length = 96, key 
length = 44). 



In this example, the replacement record is Record 0. 

The example follows: 

//JOBATLAS JOB 06#990 , SMITH, MSGLEVEL=1 

//STEP EXEC PGM=IEHATLAS 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=NEWSET,UNIT=3330,VOLUME=SER=333001 , 

// DISP=OLD 

//SYSIN DD * 

TRACK=00000002000400000008 
0000000000000000 
/* 

The control statements are discussed below: 

• SYSPRINT DD defines the device to which the output messages can be written. 

• SYSUTl DD defines the data set that contains the bad record. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• TRACK specifies the bin, cylinder, and track number for the defective track, 
and the record number, key length, and data length of the bad record. In this 
example, the input record has a bin number of zero because the device is a 
3330; it is to be placed on cylinder two, track four, record zero; and it has a 
key length of zero with a logical record length of eight. The input record in 
this example is a typical hexadecimal record as defined by a TRACK statement. 
The input record contains eight bytes (data length=8, key length=0). 
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IEHDASDR Program 



IEHDASDR is a system utility used to prepare direct access volumes for use and 
to ensure that any permanent hardware errors (that is, defective tracks) incurred 
on direct access volumes do not seriously degrade the performance of those 
volumes. (See "Introduction" for general system utility information.) 

In addition, IEHDASDR can be used to dump the entire contents or portions of a 
direct access volume to a volume or volumes of the same direct access device 
type, to a tape volume or volumes, or to a system output device. Data that is 
dumped to a magnetic tape volume is arranged so that it can subsequently be 
restored to its original organization by IEHDASDR. The direct access device types 
supported by IEHDASDR are: 2305, 2314, 2319, 3330, 3330-1, and 3340. 

The program can be used to: 

• Analyze tracks, assign alternate tracks for defective tracks, and perform 
housekeeping and formatting functions to make direct access volumes, with the 
exception of the 3330, 3330-1, and 3340, suitable for operating system use. 

Note: Defective tracks are flagged when a 3330, 3330-1, or 3340 is initialized 
at the factory. An IEHDASDR job to initialize a 3330, 3330-1, and 3340 will 
not perform a surface analysis. The ANALYZE option performs a "Quick 
DASDI" (see Table 15-1) which includes: 

1. Initialization of track zero including IPL1, IPL2, volume label, and optional 

IPLTXT. 

2. VTOC construction. 

• Perform housekeeping and formatting functions on direct access volumes 
without analyzing tracks. 

• Change the volume serial number of a formatted direct access volume. 

• Assign alternate tracks for specified defective or questionable tracks on disk 
volumes. 

• Create a backup or transportable copy of a direct access volume, or list the 
contents on a system output device. 

• Copy dumped data from a tape volume to a direct access volume. 

• Write IPL records and a program on a direct access volume. 

Initialize — With Recording-Surface Analysis 

IEHDASDR can be used to analyze the recording surface of a direct access device 



to: 



Assign alternate tracks for any disk tracks found defective during an analysis, 
or for any track previously flagged defective. Each track can be analyzed 
from 1 to 255 times, at the discretion of the user. The test of looking for 
previously flagged tracks must be suppressed when a new or unformatted, 
direct access volume is being initialized. 

Standardize each track by placing a standard home address and a record zero 
(R0) field on it. The remainder of the track is erased. 

Construct IPL bootstrap records (records 1 and 2 of track 0), a volume label 
record (record 3 of track 0), and a volume table of contents (VTOC), whose 
size and placement are determined by the user. 

IEHDASDR Program 15-1 
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• Optionally, write an IPL program record for 2305, 2314, 2319, 3330, 3330-1, 
and 3340 volumes and provide owner information in the volume label record. 

Figure 15-1 shows a direct access volume after it has been prepared for use. A 
direct access volume can be initialized in this manner using IEHDASDR. 



Standard home 
address 



IPL 

bootstrap 

records 




Figure 15-1. Direct Access Volume Initialized Using iehdasdr 

Initialize — Without Recording-Surface Analysis 

IEHDASDR can be used to prepare a direct access volume for use without 
performing a recording-surface analysis. 

A volume might be prepared for system use without recording-surface analysis 
to: 

• Check a direct access volume for previously flagged tracks. No formatting is 
performed on known defective tracks. 

• Standardize each track by placing a standard home address and a record zero 
(R0) field on it. The remainder of the track is erased (except on 3330, 3330-1, 
and 3340 volumes). 

• Construct IPL bootstrap records (records 1 and 2 of track 0), a volume label 
record (record 3 of track 0), and a volume table of contents (VTOC), whose 
size and placement are determined by the user. 

• Optionally, write an IPL program record for 2305, 2314, 2319, 3330, 3330-1, 
and 3340 devices, and provide owner information in the volume label record. 
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Changing the Volume Serial Number of a Direct Access Volume 

IEHDASDR can be used to change the volume serial number of an initialized 
direct access volume. Optionally, a one- to ten-character owner name can be 
placed in the volume label record (record 3 of track 0). If an owner name 
already exists, it is overwritten with the new name. 

Note: All cataloged data sets residing on a volume whose label is changed must 
be recataloged, if the catalog reflects the old serial number. 

Assigning Alternate Tracks for Specified Tracks 

IEHDASDR can be used to assign an alternate track on a disk volume. An 
alternate track can be assigned for any track, whether it is defective or not. If 
the specified track is an alternate, a new alternate is assigned; if the specified 
track is an unassigned alternate, it is flagged to prevent its future use. 

Creating a Backup, Transportable, or Printed Copy 

IEHDASDR can be used to dump a direct access volume or a portion of a volume 
to any number of tape volumes or volumes of the same direct access device type, 
or to a system output device. The program can dump a single track, a group of 
tracks, or an entire volume. 

When an entire volume is dumped: 

• All primary tracks (for which no alternate tracks are assigned) are dumped. 

• When a primary track is found to have an alternate track assigned, the 
alternate is dumped in place of the primary. 

Each track to be dumped will have all of its data except the home address and 
the count field of record zero (R0) copied to the receiving volume. The dump 
function of IEHDASDR is dependent on the validity of the Count field of every 
record on the track being dumped. The results of reading an erroneous Rl count 
field are unpredictable, while R2 through Rn will cause the dump function to 
terminate. 

A receiving direct access volume retains its own serial number unless the user 
specifies that it is to be assigned the serial number of the direct access volume 
being dumped. 

Except for a printing operation, only data that is owned is dumped; IEHDASDR 
checks the first or only Free Space (Format 5) data set control block (DSCB) in 
the volume table of contents. The Free Space (Format 5) DSCB identifies 
unowned (unused) space on the direct access volume. Whenever an unowned 
track is encountered, a dummy record, containing a home address and record 
zero, is written on the receiving volume. When data is dumped to a system 
output device, the entire range of specified tracks is dumped. 

A printing operation prints each record in hexadecimal. In addition, all printable 
characters are also represented in EBCDIC. 

Figure 15-2 shows the format of printed output. Each track is identified by its 
absolute track address (cccchhhh). The R0 data field is printed on the same line 
as the track address. Each printed record is preceded by a count field that 
identifies the applicable track address (cccchhhh), the record number of the 
record being printed (rr), and the key and data length (kk and dddd) of the 
record. 



IEHDASDR Program 15-3 



**• TRACK cccchhhh RO DATA xxxxxxxxxxxxxxxx 

COUNT cccchhhhrrkkdddd 

key and data fields 
^ (hexadecimal) 

000000 xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx 
— 000032 xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx 

• etc. 

_ COUNT cccchhhhrrkkdddd 

300000 xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx 
~ 300032 xxxxxxxx xxxxxxxx xxxxxxxx etc. 

• ** TRACK cccchhhh RO DATA xxxxxxxxxxxxxxxx 
COUNT cccchhhhrrkkdddd 

• 000000 xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx 
000032 xxxxxxxx xxxxxxxx etc. 


XXXXXXXX 

xxxxxxxx 
xxxxxxxx 

xxxxxxxx 


xxxxxxxx 
xxxxxxxx 

xxxxxxxx 


xxxxxxxx 

xxxxxxxx 

xxxxxxxx 
xxxxxxxx 


; 


key 


and data fields 

(EBCDIC) - 




« 















Figure 15-2. Format of a Direct Access Volume Dumped to a Printer Using IEHDASDR 

If an alternate track is printed in place of a primary track, it is identified in the 
printout by the primary track address. 

Copying Dumped Data to a Direct Access Volume 

When a direct access volume is dumped to a tape volume, the data is placed in a 
format that is specially suited for the tape volume. IEHDASDR can be used to 
restore the format of the dumped data and place the data on the same type of 
direct access volume as the original volume; that is, data originally dumped from 
a 2314 volume can be restored to a 2314 volume, etc. 

Identical copies of dumped data can be restored to any number of volumes of the 
same direct access device type as the original volume during the execution of a 
single restore operation. In addition, data that was dumped by IBCDMPRS can be 
restored. 

A receiving direct access volume retains its own serial number unless the user 
specifies that it is to be assigned the serial number of the direct access volume 
originally dumped. If multiple direct access volumes are to be dumped to, and the 
user specifies that the serial number of the dumped volume is to be propagated, 
all receiving volumes are assigned that serial number. 

Dumping and Restoring Unlike Devices 

With the 3330, 3330-1, and 3340, you have the capability of upward device 
migration. That is, a 3330 can be dumped or restored to a 3330-1 volume, but a 
3330-1 cannot be dumped or restored to a 3330. Likewise, a 3340, 35-megabyte 
model, can be dumped or restored to a 3340, 70-megabyte model, but the 
70-megabyte model cannot be dumped or restored to the 35-megabyte model. 

When any of these device migration functions are performed, the 'DOS' bit in the 
receiving volume's Format 4 DSCB is set to indicate the Format 5 DSCB is 
incorrect. It is recommended that a job step be executed to allocate a temporary 
data set for the receiving volume to cause the DADSM function to reset the DOS 
bit and correct the Format 5 DSCB. 

Writing I PL Records and a Program on a Direct Access Volume 

IEHDASDR can be used to write IPL bootstrap records and a program on cylinder 
0, track or an initialized 2305, 2314, 2319, 3330, 3330-1, or 3340 volume. 
Any online volume other than the system residence volume can be used. 
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The contents of the IPL records and the contents of the records that make up the 
program are not checked by IEHDASDR. It is the user's responsibility to ensure 
that the IPL records can load an executable program. 

The first IPL record must contain a PSW followed by two CCWs (channel 
command words). The CCWs must have the following hexadecimal formats: 



First CCW: 
Second CCW: 



06xxxxxx60000090 
08xxxxxx00000000 



The first CCW is a command to read in the second IPL record at main storage 
address xxxxxx. The second CCW is a transfer-in-channel command (a branch) to 
the CCW that begins the second IPL record. 

The second IPL record must be a 144-byte channel program. Bytes 32 to 42 of 
this record must contain zeros. 

The program may consist of: 

• One record, not longer than 3K (3072) bytes. 

• Two records, neither longer than 3K (3072) bytes. 

• Three records, none longer than 2K (2048) bytes. 

Figure 15-3 shows an input data set with three program records. 
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Figure 15-3. Input Data Set with Three Program Records 

If the output volume does not contain user labels, IEHDASDR writes program 
records after the volume label record. Figure 15-4 shows where program records 
are written when the output volume does not contain user labels. 



Writes Program Record Here 




Figure 15-4. Cylinder 0, Track Fragment Without User Labels 

If user labels have been written after the volume label, the user can specify that 

IEHDASDR: 

• Write over the user labels. 

• Put the program records after the user labels when a 2305, 3330, or 3330-1 
volume is used. 
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Figure 15-5 shows program records to be written after user labels. 



Writes Program Records Here 




Input and Output 



Figure 15-5. Cylinder 0, Track Fragment with User Labels 

The following errors are possible when using IEHDASDR to write IPL records and 
a program on a direct access volume: 

• A 2314 or 2319 output volume contains user labels, but the user has not 
specified that the user labels are to be overwritten. 

• The total input (IPL records and program) consists of fewer than three 
records. 

• The first and second IPL records are not 24 bytes and 144 bytes in length, 
respectively. 

• A third program record is longer than 2K bytes. 

• The output device is not a direct access device. 

• The output volume contains a VTOC on cylinder 0, track 0. 

• The output volume is the system residence volume. 



IEHDASDR uses as input a control data set containing utility control statements, 
and optionally, IPL text. 

The primary output or result of executing IEHDASDR is determined by the 
application. 

A sequential message data set is created to list informational messages (for 
example, control statements used), dumped data (for a print operation), and any 
error messages. 

IEHDASDR provides a return code to indicate the results of program execution. 
The return codes and their meanings are: 

• 00, which indicates successful completion. 

• 04, which indicates that an unusual condition was encountered; however, the 
overall result is successful. A warning message is issued. 

• 08, which indicates that a specified operation did not complete successfully. 
An attempt is made to perform any additional operations. 

• 16, which indicates that either an error occurred upon invoking IEHDASDR, or 
IEHDASDR was unable to open the input or message data set. The job step is 
terminated. 
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Control 

IEHDASDR is controlled by job control statements and utility control statements. 
The job control statements are used to execute or invoke IEHDASDR and define the 
data sets used and produced by IEHDASDR. 

The utility control statements are used to control the functions of the program. 

Job Control Statements 

Table 15-1 shows the job control statements necessary for using IEHDASDR. 

Table 15-1. iehdasdr Job Control Statements 

Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name PGM-IEHDASDR) or, if the job control 

statements reside in a procedure library, the procedure name. Additional 
information can be entered in the parm parameter of the EXEC statement; 
see "PARM Information on the EXEC Statement" below. 

STEPCAT Is required when a volume contains a VS AM data set which is not cataloged 

on the master catalog. 

SYSPRINT DD Defines a sequential message data set. The data set can be written to a system 
output device, a tape volume, or a direct access device. 

anyname DD Defines a direct access device type. 

tapename DD Defines a magnetic tape unit. 

SYSIN DD Defines the control data set. The control data set usually resides in the input 

stream; however, it can be defined as a blocked or unblocked sequential data 
set or as a member of a procedure library. 

The "anyname" DD statement can be entered: 

//anyname DD UNIT=xxxx,VOLUME=SER=xxxxxx,DISP«OLD 

If more than one volume is to be processed on a single mountable device, deferred 
mounting can be specified in the "anyname" DD statement by entering: 

//anyname DD UNIT=(xxxx„DEFER),VOLUME=(PRIVATE,...), 
// DISP=(NEW,KEEP) 

The "anyname" DD statement is not used for an operation that analyzes an offline 
direct access volume. 

If the volume serial number of a volume to be processed online is not known., it 
may be possible to make a nonspecific, PRIVATE volume request on a specific unit; 
for example: 

//anyname DD UNIT=(191„DEFER),VOLUME=PRIVATE,DISP=(NEW,KEEP), 
//SPACE-TRK,(1,1)) 

In this case, the operator is asked to mount a scratch volume on that unit. See 
"Appendix C: DD Statements for Defining Mountable Devices" for the appropriate 
DD statement and for a discussion of how to make a nonspecific unit request. 

If an IEHDASDR operation produces a volume serial number that is a duplicate of a 
volume serial number already allocated within the system, the volume to which the 
duplicate number is assigned is made unavailable to the system. The operator is 
asked to remove the applicable volume at the completion of the operation. 

The "tapename" DD statement can be entered: 

//tapename DD UNIT=xxxx,VOLUME=SER=xxxxxx,LABEL»(.. .,...), 
//DISP=(...,KEEP),DCB=TRTCH=C,DEN=x) 

If more than one tape volume is to be processed on the same tape unit, deferred 
mounting can be specified by: 

//tapename DD UNIT=(xxxx„DEFER),VOLUME=(PRIVATE,...) 
If standard labeled tapes are specified, the DSNAME should also be provided. 
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The "anyname" DD and "tapename" DD statements are referred to by utility 
control statements for program operation. 

Both the sysin and the sysprint data set can have a blocking factor of other 
than 1. 

Data can be dumped from the system residence volume (the IPL volume); however, 
this is the only IEHDASDR operation that can be performed on that volume. 

Because IEHDASDR can change serial numbers and existing data on a direct access 
volume, operating precautions must be followed by users who have two or more 
central processing units sharing the same direct access volume. 

If IEHDASDR is run in a multiprogramming environment, the user must choose a 
combination of DD statements (defining mountable devices) that will ensure that 
volume integrity is maintained. Refer to "Appendix C: DD Statements for Defining 
Mountable Devices." 

If non-VSAM password-protected data sets reside on volumes that are used by 
IEHDASDR, the following considerations must be made: 

• When dumping from a volume containing read password-protected data sets, 
each data set must be described in a separate DD statement having a unique 
ddname. When the program is executed, the operator must supply the correct 
password (in answer to a console message) for each password-protected data 
set. 

• When dumping to a tape volume from a direct access volume containing 
non-VSAM password-protected data sets, the DD statement defining the tape 
volume must include a DSNAME parameter. In addition, the LABEL parameter 
must define a standard labeled tape, include a PASSWORD subparameter, and 
specify or imply a file number of 1 . 

• When restoring from a tape volume, a DSNAME parameter must be included in 
the DD statement defining the tape volume. 

• During the DUMP, RESTORE, ANALYZE, and FORMAT functions (see "Utility 
Control statements"), the direct access "TO" volume is checked for 
password-protected data sets. At this time the operator must supply the correct 
password for each password-protected data set encountered. 

Refer to OS/VS1 Data Management for System Programmers, GC26-3837-0 or 
OS/VS2 System Programming Library: Data Management, GC26-3830 for 
additional information on non-VSAM data set password protection. 

If VSAM data sets reside on volumes that are used by IEHDASDR, the following 
considerations must be made: 

• All VSAM data spaces are described by a Format- 1 DSCB which indicates that 
the data set is password protected. Therefore, the catalog in which the data 
space is defined must be identified to IEHDASDR by a STEPCAT DD statement or 
defaulted to the master catalog, whether or not any VSAM data set is password 
protected. 

• The catalog master password or the VSAM data set master password must be 
supplied by the operator for all VSAM password-protected data sets within each 
data space. 

• A separate DD statement for each VSAM data set is not required as is the 
requirement for non-VSAM password-protected data sets. 

• When no non-VSAM password-protected data sets reside on a volume, the 
restore tape(s) need not be password protected. 

Refer to OS/VS Access Method Services for additional information on VSAM data 
set password protection. 
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iehdasdr can perform up to six concurrent operations of analyze, format, 
dump, or RESTORE operations (see "Utility Control Statements"). This feature, 
which can shorten the time required to execute the program, is controlled by (1) 
the number of devices defined for use and (2) the physical arrangement of utility 
control statements in the input stream. For example, assuming that the required 
devices are defined and available, a combination of six successive statements of the 
same type permits six concurrent operations to take place. However, if the utility 
control statements are arranged so that no operations of the same type appear in 
succession, no operations are performed concurrently, even though many devices 
might be defined for use. 

Note: The number of concurrent operations allowed can be overridden by an EXEC 
statement parm value. 



I 
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Restrictions 

• If IEHDASDR is used to change a volume serial number and a subsequent 
operation is performed on the newly labeled volume in the same job step, two 
"anyname" DD statements are required. The VOLUME parameter in the first 
statement includes the old volume serial number; the VOLUME parameter in 
the second statement specifies the new volume serial number. In addition, the 
second statement specifies unit affinity with the first. 

• One "anyname" DD statement is required for each device to be used in the 
job step unless the device is to be processed off line. 

• The "tapename" DD statement must be included if a data set is dumped to 
tape or if a previously dumped data set is to be restored to a direct access 
volume. 

• If BLKSIZE is specified on the SYSIN DD statement, it must be a multiple of 
80. If BLKSIZE is omitted from the statement, a block size of 80 bytes is 
assumed. 

• If BLKSIZE is specified on the SYSPRINT DD statement, it must be a multiple 
of 121. If BLKSIZE is omitted or incorrectly specified, a block size of 121 
bytes is assumed. 

• SYSIN attributes must be identical if SYSIN data sets are to be concatenated. 

PARM Information on the EXEC Statement 

The EXEC statement for IEHDASDR can contain PARM information that is used 
by the program to control line density on output listings and to indicate the 
maximum number of operations of the same type that can be performed 
concurrently in the job step. 

The exec statement can be coded: 

// EXEC PGM=IEHDASDR{,PARM='N=n' } 

{,PARM='LINECNT=xx' } 

{,PARM='LINECNT=xx,N=n } 

The LINECNT value specifies the number of lines per page in the listing of the 
SYSPRINT data set. The number xx is a 2-digit decimal number ranging from 01 
to 99. If LINECNT is omitted, the number of lines per page is 58. 

The N value specifies a decimal number from one to six that represents the 
maximum number of like functions that can be performed concurrently by 
iehdasdr, assuming that adequate system resources are available. See 0S/VS1 
Storage Estimates, GC24-5094, or 0S/VS2 Storage Estimates, GC28-0604, for the 
storage required for each operation. If N is omitted, up to six ANALYZE, 
format, dump, or RESTORE operations are performed concurrently — according 
to the number of successive like statements in the input stream. (See "Utility 
Control Statements.") 

System resources permitting, multiple output copies can be specified in any or all 
of the concurrent operations. 

For example, if N=2 and four dump statements appear in succession, the first 
two dump operations are performed concurrently. As each dump operation is 
completed and system resources become available, a new dump operation begins. 



I 
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Utility Control Statements 

The utility control statements used to control IEHDASDR are: 

ANALYZE statement, which is used to analyze the recording surface to test for 
defective tracks, assign alternates for any defective tracks found, and format 
the volume to make it ready for use. 

FORMAT statement, which is used to make a volume ready for use without 
performing an analysis of the recording surface. 

label statement, which is used to change the volume serial number of a 
direct access volume and, optionally, to update the owner field. 

GETALT statement, which is used to assign an alternate track for a specified 
track. 

DUMP statement, which is used to dump a single track, a group of tracks, or 
an entire direct access volume. 

RESTORE statement, which is used to restore a previously dumped direct 
access volume to a direct access device. 

IPLTXT statement, which signals the beginning of IPL program text statements. 

PUTIPL statement, which specifies that IPL records and a program are to be 
written on a direct access device. 

For most operations, multiple copies of a source volume can be made. The 
program can also perform from two to six ANALYZE, FORMAT, dump, or 
RESTORE operations concurrently, according to the number of successive like 
statements in the input stream; that is, up to six direct access volumes can be 
analyzed or formatted, or dumped simultaneously, or up to six magnetic tape 
(restore) volumes can be processed simultaneously. 



ANALYZE Statement 



The ANALYZE statement is used to analyze the recording surface of a direct 
access device. Bit patterns are written on a track, read, and tested for defects. If 
no defects are found, the track is formatted to make it ready for system use. 

The format of the ANALYZE statement is: 



[label] ANALYZE 



TODD= {(cuu,...)} 

{(cfdname,...)} 
,VTOC=xxxxx 
,EXTENT=xxxxx 
[,NEWVOLID=ser/a/] 
[,IPLDD=cWname] 
[,FLAGTEST= { YES } 
{NO}] 
[,PASSES= {n}] 
{0} 
[,OWNERID=name] 

[,PURGE= {YES} 
{NO}] 
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where: 

TODD= 

specifies the volume to be processed. If multiple volumes are specified in an 
ANALYZE statement and an abnormal completion of the ANALYZE operation 
occurs, the operation is terminated on all volumes. These values can be coded: 

(cuu,...) 

specifies the channel and unit address of a direct access device containing a 
volume to be initialized. This value is used only for the analysis of a volume 
offline, which includes the first analysis of a volume. If this value is coded, 
no DD statement defining a mountable device is required. When this volume 
is coded, the specified devices must be varied offline (by use of the VARY 
OFFLINE command) prior to the execution of the job step. 

(ddname,...) 

specifies the ddname of a job control statement defining a direct access 
device containing a volume to be analyzed, formatted, and labeled. Multiple 
ddnames specifying additional job control statements can be included. 

VTOC=xxxxx 

specifies a one- to five-byte decimal relative track address representing a 
primary track on which the volume table of contents is to begin. The VTOC 
cannot occupy track 0. 

EXTENT=xxxxx 

specifies the decimal length of the VTOC in tracks. The VTOC cannot extend 
into the alternate track area or onto a second volume. 

NEWVOLID=ser/a/ 

specifies a one- to six-character serial number. The serial number is assigned 
to all direct access volumes processed through the use of this control 
statement. If NEWVOLID is omitted, all direct access volumes retain their own 
serial numbers. This parameter is required for the analysis of a volume offline. 

IPLDD =ddname 

specifies the ddname of a DD statement defining the data set containing the 
IPL program. The IPL program can be included in the SYSIN (input stream) 
data set, or it can be defined as a sequential data set or a member of a 
partitioned data set. If IPL text is included in the input stream, an IPLTXT 
statement is used to separate the ANALYZE statement from the IPL program 
text statements. Maximum IPL record size is restricted to 6,496 bytes. IPLDD 
applies to 2305, 2314, 2319, 3330, 3330-1, and 3340 volumes. 

FLAGTEST= 

specifies whether a check is to be made for previously flagged tracks. When a 
volume is initialized offline, no check is made. These values can be coded: 

YES 

specifies that each track is to be checked to see if it was previously flagged 
as defective. If FLAGTEST is omitted, YES is assumed. 

NO 

specifies that the program is not to check for previously flagged tracks on 
the volume. 
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FORMAT Statement 



PASSES= 

specifies the number of passes to be made in analyzing a recording surface. 
These values can be coded: 

n 

specifies the number of times a bit pattern test is to be performed. The n 
value is a decimal number from 1 to 255. If PASSES is omitted, the bit 
pattern test is performed once on each track. 



specifies that the ANALYZE function is to bypass all surface analysis and 
track formatting, writing only a VTOC, track zero records (IPL bootstrap 
and volume label records), and IPL text if requested. The value applies to 
all direct access volumes supported by IEHDASDR. If the device is a 3330, 
3330-1, or 3340, only the specification is allowed, and is forced 
regardless of the PASSES parameter. This value is applicable to all previously 
initialized direct access devices supported by IEHDASDR while online. The 
offline "Quick DASDI" feature is supported for all direct access devices. 

OWNERID=name 

specifies a one- to ten-character name or other identifying information to be 
placed in the volume label record. OWNERID is specified as an EBCDIC 
character string with the exclusion of the blank and the comma characters 
(these terminate the control card scan of a field or an entire card). 

PURGE= 

specifies whether the ANALYZE operation is to be terminated when an 
unexpired data set is encountered. If PURGE is omitted, and an unexpired data 
set is encountered, the ANALYZE operation is terminated. These values can be 
coded: 

YES 

indicates that all unexpired data sets on the volume can be overwritten 
provided that the operator signals his concurrence when the first unexpired 
data set is encountered. 

NO 

specifies that the ANALYZE operation is to be terminated if an unexpired 
data set is encountered. If PURGE is omitted, NO is assumed. 

If PURGE=YES is coded and an unexpired data set is encountered, the operator is 
prompted. The operator replies are: 

• u, which indicates that all unexpired data sets on this volume can be 
overwritten. (The ANALYZE operation continues.) 

• T, which indicates that this volume contains unexpired data sets that must not 
be overwritten. (The ANALYZE operation is terminated.) 

The PURGE parameter does not apply to password-protected data sets; that is, the 
operator must always respond with the proper password for each 
password-protected data set encountered. If he is unable to do so, the ANALYZE 
operation is terminated. 

Note: If the device is online and a volume label and VTOC are present, they are 
read, and the information contained in them is used to initialize the volume. If 
the device is offline, the volume label and VTOC are ignored. 



The FORMAT statement is used to prepare a volume for operating-system use. 
Except for flag testing, no analysis is made prior to formatting a track. Previously 
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flagged disk tracks remain flagged; alternate tracks are assigned, where 
applicable. Because the FORMAT statement does not cause recording-surface 
analysis, it should not be used for the first initialization of a volume. 

The output includes a list of defective tracks and their assigned alternates. 

Note: If a command reject is detected while a FORMAT operation is performed 
on an assigned alternate track on an IBM 2305 Fixed Head Storage volume, 
processing continues as if no alternate track existed. No action need be taken if 
message IEH400I is typed out on the operator's console in response to this 
condition. 

If FORMAT cannot read a home address, it flags the track as being defective and 
assigns an alternate track. 

The format of the FORMAT statement is: 

[label] FORMAT TODD =(ddname,...) 

,VTOC=xxxxx 
,EXTENT=xxxxx 
[,NEWVOLID=ser/a/] 
[,IPLDD =ddname] 
[,OWNERID=name] 

[,PURGE={YES} 

{NO}] 

where: 

TODD=(ddname,...) 

specifies the ddname of a job control statement defining a direct access device 
containing a volume to be formatted. Multiple ddnames specifying additional 
job control statements can be included. If multiple volumes are specified in a 
FORMAT statement and an abnormal completion of the FORMAT operation 
occurs, the operation is terminated on all volumes. 

VTOC=xxxxx 

specifies a one- to five-byte decimal, relative track address representing a 
primary track on which the volume table of contents (VTOC) is to begin. The 
VTOC cannot occupy track 0. 

To improve performance when reading from and writing to the VTOC, it is 
recommended that every VTOC end on the last track of a cylinder (a cylinder 
boundary). This means that you should determine the starting address for the 
VTOC by subtracting the number of tracks allocated to the VTOC from the 
nearest larger track that ends on a cylinder boundary. For example, if the 
VTOC requires 5 tracks on a 3336 disk pack, which has 19 tracks per cylinder, 
the starting track should be specified as track 14, so that the VTOC will end 
on track 18 (the last track of the first cylinder). 

EXTENT=xxxxx 

specifies the decimal length of the VTOC in tracks. The VTOC cannot extend 
into the alternate track area or to a second volume. 

NEWVOLID=sena/ 

specifies a one- to six-character serial number. The serial number is assigned 
to all direct access volumes processed through the use of this control 
statement. If NEWVOLID is omitted, the direct access volumes retain their own 
serial numbers. 

IPLDD =ddname 

specifies the ddname of a DD statement defining the data set containing the 
IPL program. The IPL program can be included in the SYSIN (input stream) 
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data set, or it can be defined as a sequential data set or a member of a 
partitioned data set. If IPL text is included in the input stream, an ipltxt 
statement is used to separate the FORMAT statement from the program text 
statements. Maximum IPL record size is restricted to 6,496 bytes. This 
parameter applies to 2305, 2314, 2319, 3330, 3330-1, and 3340 volumes. 

OWNERID=name 

specifies a one- to ten-character name or other identifying information to be 
placed in the volume label record. OWNERID is specified as an EBCDIC 
character string with the exclusion of the blank and the comma characters 
(these terminate the control card scan of a field or an entire card). 

PURGE= 

specifies whether the FORMAT operation is to be terminated when an 
unexpired data set is encountered. If PURGE is omitted and an unexpired data 
set is encountered, the FORMAT operation is terminated. These values can be 
coded: 

YES 

indicates that all unexpired data sets on the volume can be overwritten 
provided that the operator signals his concurrence when the first unexpired 
data set is encountered. 

NO 

specifies that the FORMAT operation is to be terminated when an unexpired 
data set is encountered. If PURGE is omitted, NO is assumed. 

If PURGE=YES is coded and an unexpired data set is encountered, the operator is 
prompted. The operator replies are: 

• U, which indicates that all unexpired data sets on this volume can be 
overwritten. (The FORMAT operation continues.) 

• T, which indicates that this volume contains unexpired data sets that must not 
be overwritten. (The FORMAT operation is terminated.) 

The PURGE parameter does not apply to password-protected data sets; that is, the 
operator must always respond with the proper password for each 
password-protected data set encountered. If he is unable to do so, the FORMAT 
operation is terminated. 



LABEL Statement 



The label statement is used to change the serial number of a direct access 
volume and, optionally, to update the owner field in record 3 of track 0. One 
label statement must be included for each volume that is to have its label 
changed. 

The format of the LABEL statement is: 



[label] LABEL 



TODD= {cuu} 

{ddname} 
,NEWVOLID=seria/ 

[,OWNERID=name] 
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GETALT Statement 



DUMP Statement 



where: 

TODD= 

specifies the volume to be processed. These values can be coded: 

cuu 

specifies the channel and unit address of a direct access device containing a 
volume whose serial number is to be changed. This value is used only for 
labeling an offline volume. If this value is coded, no DD statement defining 
a mountable device is required. When this value is coded, the specified 
device must be varied off line (by use of the VARY OFFLINE command) 
prior to the execution of the job step. 

ddname 

specifies the ddname of a job control statement defining a direct access 
device containing a volume whose serial number is to be changed. 

NEWVOLID=seria/ 

specifies a one- to six-character serial number. The serial number is assigned 
to the direct access volume processed through the use of this control 
statement. 

OWNERID= name 

specifies a one- to ten-character name or other identifying information. If 
OWNERID is omitted, the old owner information, if any, is retained. OWNERID 
is specified as an EBCDIC character string with the exclusion of the blank, the 
dash, and the comma characters (these terminate the control card scan of a 
field or an entire card). 



The GETALT statement is used to assign an alternate track for a specified disk 
track if the volume was previously initialized. 

Flags set by GETALT statement, for defective 3330, 3330-1, or 3340 tracks, 
cannot be removed by IEHDASDR. 

The format of the GETALT statement is: 



[label] GETALT 



TODD=ddname 
,TRACK=ccccW?hh 



where: 



TODD=dcfname 

specifies the ddname of a job control statement defining a disk device 
containing a volume on which an alternate track is to be assigned. 

TRACK= cccchhhh 

specifies in hexadecimal the cylinder number, cccc, and head number, hhhh, of 
a track for which an alternate track is requested. TRACK cannot specify track 
or the first track occupied by the VTOC. 



The DUMP statement dumps a single track, a group of consecutive tracks, or an 
entire direct access volume to one or more direct access volumes of the same 
device type, to one or more tape volumes, or to a system output device (printer 
assumed). When dumping more than one file to the same tape volume, the tape 
is rewound to the load point at the end of each dump operation. 

A detailed description of the tape volume format is available in OS/VS Utilities 
Logic, SY35-0005. 
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The format of the DUMP statement is: 

[label] DUMP FROMDD =ddname 
,TODD=(ddname,...) 
[,CPYVOLID= {YES} 
{NO}] 
[,BEGIN=cccchhhh] 
[,END =cccchhhh] 

[,PURGE={YES} 

{NO}] 

where: 

FROMDD =ddname 

specifies the ddname of the DD statement defining the device containing the 
direct access volume from which a copy or copies are to be made. 

TODD=(ddname,...) 

specifies the ddname of the system output device (SYSPRINT) or specifies the 
ddnames of the DD statements defining the devices containing the direct 
access or tape volumes on which copies are to be made. If TODD=SYSPRINT is 
coded, the direct access volume described by FROMDD is dumped to the 
system output device. If a permanent data check or missing address marker is 
encountered while reading the direct access volume, the defective records are 
identified and printed. The output may exceed the expected data size due to a 
data check in the count field of the error record. When dumping from a 2305, 
3330, 3330-1, or 3340 to SYSPRINT, the SPACE parameter may be necessary 
on the SYSPRINT DD card. Allocate sufficient space, for example, "CYL,(5,5)", 
to allow large capacity devices to dump to SYSPRINT. 

CPYVOLID= 

specifies whether receiving direct access volumes are to be assigned the serial 
number of the dumped volume. If CPYVOLID is omitted, receiving volumes 
keep their own serial numbers. These values can be coded: 

YES 

specifies that all receiving direct access volumes are to be assigned the serial 
number of the dumped volume. 

NO 

specifies that receiving volumes are to keep their own serial numbers. This 
is the default. 

BEGIN=cccchhhh 

specifies in hexadecimal a cylinder number, cccc and head number, hhhh, that 
identify the first track to be dumped. If BEGIN is omitted, the dump operation 
begins with track 0. 

END=cccchhhh 

specifies in hexadecimal a cylinder number, cccc, and head number, hhhh, that 
identify the last track to be dumped. If only one track is to be dumped, both 
BEGIN and END specify that track address. If END is omitted, the last primary 
track of the volume is the last track to be copied. (Alternate tracks are not 
dumped unless they are assigned as alternates.) 
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PURGE= 

specifies whether the dump operation is to be terminated when an unexpired 
data set is encountered. If PURGE is omitted, the dump operation is terminated 
when an unexpired data set is encountered. PURGE does not apply when 
dumping to a restore tape. These values can be coded: 

YES 

indicates that all unexpired data sets on a receiving direct access volume 
can be overwitten, provided that the operator signals his concurrence when 
the first unexpired data set is encountered. 

NO 

specifies that the dump operation is to be terminated when an unexpired 
data set is encountered. This is the default. 

If PURGE=YES is coded and an unexpired data set is encountered, the operator is 
prompted. The operator replies are: 

• U, which indicates that all unexpired data sets on the receiving direct access 
volume can be overwritten. (The DUMP operation continues.) 

• T, which indicates that the receiving direct access volume contains unexpired 
data sets that must not be overwritten. (The DUMP operation is terminated.) 

The PURGE parameter does not apply to password-protected data sets; that is, the 
operator must always respond with the proper password for each 
password-protected data set encountered. If he is unable to do so, the dump 
operation is terminated. 

An extra input/output error (data check) message is generated at the console 
when the dump to SYSPRINT function encounters one of the following conditions: 

• Missing address marker. 

• Data check in count and key fields and/or data field. 

• Input/output error on a search command. 

• Missing address marker and no record found. 

The additional data check message printed at the console is generated by the 
dump function's error recovery procedure. However, the additional message is 
not reflected by a SYNADAF message in the SYSPRINT data set. If a missing 
address marker is encountered during a space count command, the function 
terminates with a return code of 8. 

Note: If multiple output volumes are specified in a DUMP statement and an 
abnormal completion of the DUMP operation occurs, the operation is terminated 
on all output volumes. 

Do not dump a volume and restore new data to that volume in the same job 
step. IEHDASDR does not flush the input stream if an operation is unsuccessful; 
that is, the program attempts to perform any remaining functions after 
encountering an error. Thus, if a dump operation is unsuccessful, data is lost if a 
subsequent restore operation places new data on the dumped volume. 

Partial dumps of direct access volumes should be used with extreme caution. 
Because only those tracks that are dumped are placed on the receiving volumes, 
the partially dumped data may not be usable. When partially dumped data is 
subsequently restored, it is placed on the same tracks that it originally occupied. 

When using the DUMP statement, do not specify the same ddname in more than 
one TODD parameter in a single job step, except when the ddname is SYSPRINT. 
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RESTORE Statement 



When space permits, more than one direct access volume can be dumped to a 
restore tape. However, IEHDASDR creates two files for each volume of data that 
is dumped. Therefore, the LABEL parameter sequence number in the DD 
statement defining the restore volume must be coded as 3, 5, 7, etc. for the 
second, third, fourth, etc. volume dumped to the restore tape. 

In the case of an IPL restore tape, the LABEL parameter sequence number must 
be coded as 2, 4, 6, etc. for the first, second, third, etc. volume dumped to the 
restore tape. 

The files are referred to in the same manner when restoring data to a direct 
access device. 

When processing an unlabeled tape before a dump operation, the IEHDASDR 
writes an end-of-file record (tapemark) and continues processing. 

When dumping to or restoring from a tape, specified as standard label or "BLP", 
a disposition of KEEP should be specified in the DD statement for the tape. 
Unlabeled tapes may have other disposition parameters. 

When restoring from a restore file on a tape, the same file sequence number and 
tape label format used in the dump operation must be used. 

Intermixing of restore files with system data sets is not recommended because of 
the unique format of the restore file. 



The RESTORE statement is used to restore a direct access volume or volumes 
from a tape volume on which a dumped copy was previously placed. 

Note: When a standard labeled restore tape created by IBCDMPRS is restored by 
IEHDASDR, the DD card describing the tape for IEHDASDR can specify 
LABEL=(2,BLP). Bypass label processing must have been system generated by 
specifying OPTlONS=BYLABEL on the SCHEDULR control card. If bypass label 
processing is not available, any standard labeled tape created by IBCDMPRS can 
be restored by IEHDASDR, by providing appropriate DCB parameters on the DD 
statement for the tape (RECFM=U, BLKSlZE=track length). 

The formal; of the RESTORE statement is: 



[label] RESTORE 



TODD=(ddname,...) 
FROMDD=ddname 
[CPYVOLID= {YES} 
{NO}] 
[PURGE= {YES} 
{NO}] 



where: 



TODD=(ddname,...) 

specifies the ddnames of the DD statements defining the devices containing the 
direct access volumes to be restored. If multiple output volumes are specified 
in a RESTORE statement and an abnormal completion of the restore operation 
occurs, the operation is terminated on all output volumes. 

FROMDD=ddname 

specifies the ddname of the DD statement that defines the tape volume 
containing the data to be restored. If more than one tape volume is to be used 
as input, the DD statement for the tape must indicate multiple volumes. 
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IPLTXT Statement 



PUTIPL Statement 



CPYVOLID 

specifies whether restored direct access volumes are to be assigned the serial 
number of the dumped direct access device. If CPYVOLID is omitted, receiving 
volumes keep their own serial numbers. These values can be coded: 



YES 



specifies that all restored direct access volumes are to be assigned the serial 
number of the dumped direct access volume. 

NO 

specifies that receiving volumes are to keep their own serial numbers. This 
is the default. 

PURGE= 

specifies whether the restore operation is to be terminated when an unexpired 
data set is encountered. If PURGE is omitted, the restore operation is 
terminated when an unexpired data set is encountered. 

YES 

specifies that all unexpired data sets on the receiving direct access volume 
can be overwritten provided that the operator signals his concurrence when 
the first unexpired data set is encountered. 

NO 

specifies that the restore operation is to be terminated if an unexpired data 
set is encountered. This is the default. 

If PURGE=YES is coded and an unexpired data set is encountered, the operator is 
prompted. The operator replies are: 

• u, which indicates that all unexpired data sets on this volume can be 
overwritten. (The restore operation continues.) 

• T, which indicates that this volume contains unexpired data sets that must not 
be overwritten. (The restore operation is terminated.) 

The PURGE parameter does not apply to password-protected data sets; that is., the 
operator must always respond with the proper password for each 
password-protected data set encountered. If he is unable to do so, the restore 
operation is terminated. 



The IPLTXT statement is used to mark the beginning of IPL program text 
statements. The IPL text must follow the first statement referring to it. 

IPL text need be included only once in the input stream; that is, IEHDASDR refers 
to the first copy of IPL text encountered when performing multiple functions in a 
single job step. 

The format for the IPLTXT statement is: 

[label] IPLTXT 



The PUTIPL statement specifies that IPL bootstrap records and a program are to 
be read from an input data set and written to cylinder 0, track of a direct 
access volume. As a result, cylinder 0, track of the output volume will contain 
a program that the user should be able to load from the console. 
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The format of the PUTIPL statement is: 

[label] PUTIPL FROMDD =ddname 
,TODD=ddname 
[,PURGE={YES} 

{NO}] 

where: 

FROMDD=ddname 

specifies the ddname of the DD statement that identifies the input data set. 
(The DD statement must contain the DSNAME and DISP parameters and, if the 
input data set is not cataloged or passed from an earlier step, the VOL and 
UNIT parameters.) 

TODD =ddname 

specifies the ddname of the DD statement that identifies the volume serial 
number of the output volume. (The unit parameter must specify a 2305, 
2314, 3330, 3330-1, or 3340 volume, and DISP must equal OLD. VOL must 
not specify the system residence volume.) The input data set must be in the 
form of from three to five variable length records. The first two records must 
be IPL1 and IPL2 type records with record lengths of exactly 24 (IPL1) and 144 
IPL2) bytes. The remaining one to three records must have a cumulative length 
not greater than the remaining track capacity with a 3072 byte maximum size 
for any one of the three records. (See "Writing IPL Records and a Program on 
a Direct Access Volume" for IPL records format description.) 

PURGE= 

specifies whether user labels are to be overwritten. These values can be coded: 

YES 

specifies that the program may be written over any user labels or over any 
data that follows the volume label record. 

NO 

specifies that the program may not be written over standard user labels. If 
the output device is a 2305, 3330, 3330-1, or 3340, the program is written 
following any standard user labels. If the output volume contains user labels 
and the output device is a 2314 or 2319, there may not be enough space on 
the track for a program; in this case, the write operation is terminated. If 
PURGE is omitted, NO is assumed. 



The following examples illustrate some of the uses of IEHDASDR. Table 15-2 can 
be used as a quick reference guide to IEHDASDR examples. The numbers in the 
"Example" column point to examples that follow. 
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Table 15-2. 


iehdasdr Example Directory 




Operation 


DeWce 


Comments 


Example 


INITIALIZE 


2314 Disk 


Volume is to be initialized for the first time; 
therefore, recording surface is analyzed, ipl 
test is included in the input stream. 


1 


INITIALIZE 


2314 Disks 


Three previously initialized volumes are to 
be initialized; their volume serial numbers are 
to be changed. Surface analysis is to be 
performed at the same time. 


2 


GETALT 
and LABEL 


3330 Disk 


Get alternate tracks for a previously initialized 
volume and change its volume serial number. 


3 


DUMP 


2314 Disks 


Dump a copy of one volume to three other 
volumes. 


4 


DUMP 


2305-1 Disk, 
system output 
device 


Dump a group of tracks to the system output 
device, which is assumed to be a printer. 


5 


DUMP 


2314 Disk, 
9-track Tape 


Dump a disk volume to magnetic tape. Only 
tape, is to be restored to direct access. 


6 


RESTORE 


3330 Disks, 
7-track Tape 


A 3330 disk volume, previously dumped to 
tape, is to be restored to direct access. 


7 


DUMP and 
RESTORE 


2314 Disks, 
9-track Tape 


Dump operations are to be performed 
concurrently to minimize input/output time. 
Restore operations are to be performed 
concurrently to minimize input/output time. 


8 


RESTORE 


9-track Tape, 
2314 Disk 


A 2314 volume, previously dumped to two tape 
volumes, is to be restored to disk. 


9 


WRITE 
PROGRAM 


2305-2 Disk, 
2314 Disk 


Write IPL bootstrap records and a program 
on track of a direct access volume. 


10 


FORMAT 


3330 Disk 


Format a disk by writing an R0 on 
each track. The IPL text is included 
in the input stream. Volume serial 
is changed. 


11 


FORMAT 


3330 Disk 


Format two disks. 


12 


"Quick 
DASDI" 


3330 Disk 


Uses ANALYZE function to build VTOC 
and change volume serial number. 


13 


DUMP and 
RESTORE 


3330 Disk, 
9-track Tape 


VSAM and non-VSAM password-protected data 
sets are dumped and then restored. 


14 



In this example, a blank 2314 volume is to be analyzed and formatted for the first 
time. Because this example deals with a blank volume, two considerations must be 
made: 

1. The TODD parameter in the ANALYZE statement must specify a channel and unit 
address, rather than a ddname. 

2. The selected device (in this example, unit 130) must be varied offline by the 
operator; that is, before the job is executed, the operator must use the VARY 
offline command. 
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The example follows: 

//DASDR1 JOB 

// EXEC PGM=IEHDASDR 

//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 

ANALYZE TODD= 130, VTOC=00004 , EXTENT=000 1 , 
NEWVOLID=23 1 400 , OWNERID=SMITH , 
IPLDD=SYSIN , FLAGTEST=NO 
IPLTXT 

IPL TXT (text) statements 



72 
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END 
/* 

The control statements are discussed below: 

• SYSIN- DD defines the control data set, which follows in the input stream. 

• ANALYZE defines a mountable device on which a blank 2314 volume is to be 
mounted. This statement defines the starting location and extent of a VTOC, 
specifies a serial number and owner identification, indicates that no flag testing 
is to be performed, and indicates that IPL text is included in the input stream. 

• IPLTXT signals the start of IPL text. 

• END signals the end of IPL text. 



In this example, three previously initialized 2314 volumes are to be initialized 
and assigned new serial numbers. 



The example follows: 



72 



//DASDR2 

// 

//SYSPRINT 
//VOL1 
// VOLUME=( 
//VOL2 
// VOLUME=( 
//VOL3 
// VOLUME=( 
//SYSIN 
ANALYZE 

ANALYZE 

ANALYZE 

/* 



JOB 

EXEC PGM=IEHDASDR 
DD SYSOUT=A 

DD UNIT=( 2314, , DEFER ),DISP=OLD, 
PRIVATE , , SER=( 231400)) 
DD UNIT=( 2314, , DEFER ),DISP=OLD, 
PRIVATE, ,SER=( 231401 ) ) 
DD UNIT=( 2314, , DEFER ),DISP=OLD, 
PRIVATE, ,SER=( 231402 ) ) 
DD * 
TODD=VOL1 , VTOC=00003 , EXTENT=000 1 , 

OWNERID=SMITH , NEWVOLID=DISK0 1 , FLAGTEST=NO 
TODD=VOL2 , VTOC=00006 , EXTENT=000 1 , 

OWNERID=SMITH , NEWVOLID=DISK02 , FLAGTEST=NO 
TODD=VOL3 , VTOC=00004 , EXTENT=000 1 , 

OWNERID=SMITH , NEWVOLID=DISK03 , FLAGTEST=NO 



The control statements are discussed below: 

• VOL1, VOL2, and VOL3 DD define three 2314 devices on which the volumes to 
be initialized are mounted. 

• SYSIN DD defines the control data set, which follows in the input stream. 
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The ANALYZE statements indicate the ddnames of DD statements defining 
devices on which the three 2314 volumes (231400, 231401, and 231402) are 
to be mounted. The ANALYZE statements also define starting locations and 
extents of the three VTOCs, specify new owner names and serial numbers 
(DISK01, DISK02, and DISK03), and indicate that no flag testing is to be 
performed on these volumes. 



In this example, alternate tracks are to be assigned for three suspected defective 
tracks on a 3330 volume. 

The example follows: 

//DASDR3 JOB 

// EXEC PGM=IEHDASDR 

//SYSPRINT DD SYSOUT=A 

//VOLUME1 DD UNIT=( 3330, , DEFER ),DISP=OLD, 

// VOLUME=( PRIVATE, ,SER=( 333000 ) ) 

//SYSIN DD * 

TODD= VOLUME 1 , TRACK=0005001 1 

TODD=VOLUME1 ,TRACK=00A00007 

TODD=VOLUME 1 , TRACK= 01010002 

TODD=VOLUME1 , NEWVOLID=DISK00 , OWNERID=SMITH 



GETALT 

GETALT 

GETALT 

LABEL 



/* 



The control statements are discussed below: 

• VOLUMEl DD defines a device that is to contain the 3330 volume (333000). 

• SYSIN DD defines the control data set, which follows in the input stream. 

• The GETALT statements specify the ddname of the DD statement defining the 
device on which the 3330 volume is mounted. The GETALT statements specify 
the relative track addresses of the tracks for which alternates are to be 
assigned. 

• label specifies the ddname of the DD statement defining the device on which 
the 3330 volume is mounted. The LABEL statement changes the serial number 
of the 3330 volume from 333000 to DISK00. 



In this example, a copy of an entire volume (231400) is to be dumped to three 
volumes (231401, 231402, and 231403). 



The example follows: 



//DASDR4 JOB 

// EXEC PGM=IEHDASDR 

//SYSPRINT DD SYSOUT=A 

//DUMPFROM DD UNIT=( 23 1 4 , , DEFER ) ,DISP=OLD, 
// VOLUME=( PRIVATE, , SER=( 23 1 400 ) ) 
//DUMPT01 DD UNIT=( 2314, , DEFER ) ,DISP=OLD, 
// VOLUME=( PRIVATE, ,SER=( 231401 )) 
//DUMPT02 DD UNIT=( 23 1 4 , , DEFER ) ,DISP=OLD, 
// VOLUME=( PRIVATE, ,SER=( 231402 ) ) 
//DUMPT03 DD UNIT=( 231 4 , , DEFER ) ,DISP=OLD, 
// VOLUME=( PRIVATE, ,SER=( 231403 ) ) 
//SYSIN DD * 
DUMP FROMDD=DUMPFROM , TODD= ( DUMPT0 1 , DUMPTO 2 , DUMPTO 3 
PURGE=YES 
/* 
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IEHDASDR Example 6 



The control statements are discussed below: 

• DUMPFROM DD defines a mountable device that is to contain a source 
volume. 

• DUMPTOl, DUMPT02, and DUMPT03 DD define mountable devices that are to 
contain the three receiving volumes. 

• dump specifies the dump operation and identifies the DD statements defining 
the applicable devices. All receiving volumes are to retain their own serial 
numbers. 



In this example, a copy of tracks through 60 is to be dumped from a disk 
volume (230500) to a system output device. 

The example follows: 

//DASDR5 JOB 

// EXEC PGM=IEHDASDR 

//SYSPRINT DD SYSOUT=A 

//DEV DD UNIT=2305-1 ,DISP=OLD, 

// VOLUME=( PRIVATE, ,SER=( 230500 ) ) 

//SYSIN DD * 

DUMP FROMDD=DEV, TODD=SYSPRINT , BEGIN=00000000 , END=00070004 
/* 

The control statements are discussed below: 

• DEV DD defines a device that is to contain the source volume. 

• DUMP specifies the dump operation, identifies the DD statements defining the 
source and receiving devices, and identifies the tracks that are to printed. 



In this example, a 2314 volume (231400) is to be dumped to a 9-track, 800 bits 
per inch, tape volume (240000). 

The example follows: 

//DASDR6 JOB 

// EXEC PGM=IEHDASDR 

//SYSPRINT DD SYSOUT=A 

//SOURCE DD UNIT=( 2314, , DEFER ) ,DISP=OLD, 

// VOLUME=( PRIVATE, ,SER=( 231400 ) ) 

//RECEIVE DD UNIT=( 2400 ,, DEFER ) ,DISP=NEW,DSNAME=TAPE1 , 

// VOLUME=( PRIVATE, ,SER=( 240000 ) ) 

//SYSIN DD * 

DUMP FROMDD=SOURCE , TODD=RECEIVE 
/* 

Note: This example assumes that only one tape volume is required. If more than 
one is required, code the volume serial numbers of the additional volumes in the 
VOLUME parameter of the DD statement that defines the magnetic tape device. 
For unlabeled tapes, include a volume count in the DD statement. 

The control statements are discussed below: 

• SOURCE DD defines a mountable device that is to contain the source volume. 

• RECEIVE DD defines a 9-track tape drive that is to contain the receiving tape 
volume. 

• dump specifies the dump operation and identifies the DD statements defining 
the source and receiving devices. 
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In this example, three disk volumes (333000, 333001, and 333002) are to be 
restored from a 7-track, 556 bits per inch, standard-labeled tape volume. 

The example follows: 

//DASDR7 JOB 

// EXEC PGM-IEHDASDR 

//SYSPRINT DD SYSOUT=A 

//TAPE DD UNIT=( 2400-2, , DEFER ),DISP=OLD, 

// DCB=(TRTCH=C,DEN=1 ) , DSNAME=TAPE 1 , 

// VOLUMES PRIVATE, ,SER=( 240000 ) ) 

//DIRACC1 DD UNIT=( 3330, , DEFER ),DISP=OLD, 

// VOLUME=( PRIVATE , , SER=( 333000 ) ) 

//DIRACC2 DD UNIT=( 3330 ,, DEFER ) ,DISP=OLD, 

// VOLUME=( PRIVATE, ,SER=( 333001 ) ) 

//DIRACC3 DD UNIT=( 3330 ,, DEFER ), DISP=OLD, 

// VOLUME^ ( PRIVATE , , SER= (333002)) 

//SYSIN DD * 

RESTORE TODD=( DIRACC1 ,DIRACC2 , DIRACC3 ) , FROMDD=TAPE 
/* 

The control statements are discussed below: 

• TAPE DD defines a 7-track tape unit that is to contain the source tape volume. 

• DlRACCl, DIRACC2, and DIRACC3 DD define mountable devices that are to 
contain the three receiving volumes. 

• RESTORE specifies the restore operation and identifies the DD statements 
defining the source and receiving devices. The receiving volumes retain their 
own serial numbers. 



In this example, two direct access volumes are to be dumped concurrently to two 
receiving volumes in one operation; two direct access volumes are to be restored 
concurrently from two 9-track, 800 bits per inch, standard-labeled tape volumes 
in another operation. 

The example follows: 

//DASDR8 JOB 

// EXEC PGM=IEHDASDR 

//SYSPRINT DD SYSOUT=A 

//SOURCE 1 DD UNIT=( 2314, , DEFER ),DISP=OLD, 

// VOLUME=( PRIVATE, ,SER=( 231400 ) ) 

//SOURCE2 DD UNIT=( 23 1 4 , , DEFER ) ,DISP=OLD, 

// VOLUME=( PRIVATE, ,SER=( 231401 )) 

//T01 DD UNIT=2314,VOLUME=SER=231402,DISP=OLD 

//T02 DD UNIT=2314,VOLUME=SER=231403,DISP=OLD 

//SOURCE3 DD UNIT=( 2400 ,, DEFER ) ,DISP=OLD, LABEL=( ,NL ) , 

// VOLUME=( PRIVATE, ,SER=( 240000 ) ) 

//SOURCE4 DD UNIT=( 2400 ,, DEFER ) ,DISP=OLD, LABEL=( ,NL ) , 

// VOLUME=( PRIVATE, ,SER=( 240001 ) ) 

//T03 DD UNIT=AFF=T01 , VOLUME=SER=23 1 404 ,DISP=OLD 

//T04 DD UNIT=AFF=TO2,VOLUME=SER=231405,DISP=OLD 

//SYSIN DD * 

DUMP FROMDD=SOURCE1 ,TODD=T01 
DUMP FROMDD=SOURCE2,TODD=T02 

RESTORE TODD=T03,FROMDD=SOURCE3 

RESTORE TODD=T04 , FROMDD=SOURCE4 
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The control statements are discussed below: 

• SOURCE l and SOURCE2 DD define devices on which the source volumes for 
the dump operation are to be mounted. 

• TOl and T02 DD define devices on which the receiving volumes for the dump 
operation are to be mounted. 

• SOURCE3 and SOURCE4 DD define devices on which the source tape volumes 
for the restore operation are to be mounted. 

• T03 and T04 DD define devices on which the receiving direct access volumes 
for the restore operation are to be mounted. The receiving volumes for the 
restore operation are to be mounted on the same devices as the receiving 
volumes for the dump operation were mounted. 



In this example, a 2314 volume previously dumped to tape is to be restored. 
Because a completely filled 2314 volume requires more space than is available on 
a single reel of 9-track, 800 bits per inch tape, two tape volumes were used in 
the dump operation. 

The example follows: 

//DASDR9 JOB 00#990, SMITH 

// EXEC PGM= IEHDASDR 

//SYSPRINT DD SYSOUT^A 

//TAPE DD UNIT=2400,VOL=( ,, ,2,SER=( 240000,2400001 ) ), 

// DISP^OLD 

//DISK DD UNIT=2314,VOL=SER=231400,DISP=OLD 

//SYSIN DD * 

RESTORE FROMDD=TAPE,TODD=DISK 
/* 

The control statements are discussed below: 

• TAPE DD defines the 9-track tape volumes that contain the data to be restored 
to disk. 

• DISK DD defines the 2314 volume to which data is to be restored. 

• RESTORE specifies that data is to be restored from the tape volumes defined in 
the TAPE DD statement to the 2314 volume defined in the DISK DD statement. 

Note: For unlabeled tapes, use the external volume identification and the 
label=(,NL) parameter on the associated tape DD card. 



In this example, IPL bootstrap records and a program are to be written on track 
of a direct access volume. 

The example follows: 

//DASDR10 JOB 

// EXEC PGM=IEHDASDR 

//SYSPRINT DD SYSOUT=A 

//INPUT DD DSNAME=IPLPROG,UNIT=2305-2, 

// VOL=SER=230502,DISP=OLD 

//OUTPUT DD UNIT=2314,VOL=SER=231401 ,DISP=OLD 

//SYSIN DD * 

PUTIPL FROMDD=INPUT , TODD=OUTPUT , PURGE=YES 
/* 

The control statements are discussed below: 

• INPUT DD defines the input data set, which contains the IPL records and 
program to be written. The input data set resides on a 2305 volume. 
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• OUTPUT DD defines the output data set, which is to reside on a 2314 volume. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• PUTIPL identifies the DD statements (INPUT and OUTPUT) that define the input 
and output data sets and specifies that the program to be written on the 2314 
volume can be written over any data after the volume label record. 

Note that the 2319 is functionally equivalent to the 2314; to use a 2319 volume, 
specify 2314. 



In this example, a 3330 volume is formatted and assigned a new serial number. 

The example follows: 

72 
//DASDR1 1 JOB 

// EXEC PGM-IEHDASDR 

//SYSPRINT DD SYSOUT=A 

//DISK DD UNIT=3330,DISP=OLD,VOL=( PRIVATE, 
// SER=( 333000) ) 
//SYSIN DD * 

FORMAT TODD=DISK,VTOC=00006,EXTENT=00005, C 

NEWVOLID=333001 , PURGE=YES , IPLDD=SYSIN 

IPLTXT 

IPL TXT (text) statements 



END 
/* 

The control statements are discussed below: 

• DISK dd defines the 3330 device on which the volume (333000) is mounted. 

• SYSIN DD defines the control data set which follows in the input stream. 

• FORMAT defines a starting location and extent of a volume table of contents, 
specifies a new serial number, and indicates that the IPL text is included in the 
input stream. Record R0 of each track is rewritten. 

• IPLTXT signals the start of IPL text. 

• END signals the end of IPL text. 

In this example, two 3330 volumes are formatted. 

The example follows: 

//DASDR12 JOB 

// EXEC PGM=IEHDASDR 

//SYSPRINT DD SYSOUT=A 

//DISK01 DD UNIT=3330,DISP=OLD,VOL=( PRIVATE, ,SER=( 333001 ) ) 

//DISK02 DD UNIT=3330,DISP=OLD,VOL=( PRIVATE, ,SER=( 333002 ) ) 

//SYSIN DD * 

FORMAT TODD=(DISK01 ,DISK02 ) , VTOC-00009 ,EXTENT=0001 
/* 

The control statements are discussed below: 

• DISK01 and DISK02 DD define the 3330 devices on which the volumes (333001 
and 333002) are mounted. 

• FORMAT defines a starting location and extent of a volume table of contents. 
The R0 of each track is rewritten. 
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IEHDASDR Example 13 



In this example a 3330 volume is initialized with a VTOC and volume serial 
number — or "Quick DASDI" is performed. 

The example follows: 

//DASDR13 JOB 

// EXEC PGM=IEHDASDR 

//SYSPRINT DD SYSOUT=A 

//DISK DD UNIT=3330,DISP=OLD, 

// VOL=( PRIVATE,, SER=( 333000)) 
//SYSIN DD * 

ANALYZE TODD=DISK, VTOC=000 1 9 , EXTENT=000 1 9 , 
NEWVOLID=333333 
/* 

The control statements are discussed below: 

• disk DD defines the 3330 device on which the volume (333000) is mounted. 

• ANALYZE defines the starting location and extent of the volume table of 
contents. For 3330 devices, PASSES-0 is the default so that only a "Quick 
dasdi" is performed. 
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In this example a 3330 volume containing VSAM and non-vSAM 
password-protected data sets is dumped to a 9-track, 6250 bits per inch, standard 
labeled tape and then restored. 



//DASDR14 JOB 
//D14STEP1 EXEC 
//STEPCAT DD 
//SYSPRINT DD 
//DISK1 DD 
//TAPE1 DD 



//D14STEP2 EXEC 
//STEPCAT DD 
//SYSPRINT DD 
//DISK2 DD 
//TAPE 2 DD 



PGM=IEHDASDR 

DSNAME=VSAMCAT1 ,DISP=SHR 

SYSOUT=A 

UNIT=3330,VOL=SER=333000,DISP=OLD 

UNIT=3400,DISP=NEW,DSNAME=TAPE1 , 
// VOL=( , , ,2, SER=( 34000 1 , 340002 ) ) , 
// LABEL=( , SL , PASSWORD ) , DCB=DEN=4 

//DISKA DD UNIT=3330,VOL=SER=333000,DISP=OLD, 
// DSNAME=DATASET1 
//SYSIN DD * 

DUMP FROMDD=DI SK 1 , TODD=TAPE 1 

/* 

PGM= IEHDASDR 

DSNAME=VSAMCAT1 ,DISP=SHR 

SYSOUT=A 

UNIT=3330,VOL=SER=333000,DISP=OLD 

UNIT=3400,DISP=OLD,DSNAME=TAPE1 , 
// VOL=( ,, ,2, SER=( 34000 1,340002 ) ),LABEL=( ,SL) 
//SYSIN DD * 

RESTORE TODD=DI SK2 , FROMDD=TAPE2 
/* 

The control statements are discussed below: 

• The STEPCAT DD statements define a VSAM user catalog in which VSAM data 
sets on the volume are cataloged. The data sets are not cataloged in the master 
catalog. This must be provided even when no data sets are VSAM password 
protected. 

• tapei defines a tape unit upon which a three-volume data set resides. This data 
set must be password protected when any non-VSAM data sets on the volume are 
password protected. If no non-VSAM password data sets reside on the volume, 
the tape need not be password protected. 

• DlSKl defines the device that is to contain the source volume. 

• DISKA defines a non-VSAM password-protected data set which resides on the 
source volume. This is necessary since password prompting is by DDname and 



15-28 OS/VS Utilities 



would cause confusion if more than one non-VSAM password-protected data set 
resided on the volume. 

• DISK2 defines the device that is to contain the receiving volume. 

• TAPE2 defines the tape unit that is to contain the source tape volumes. 

• D14STEP1, during this job step the operator will be required to provide the 
password for each non-VSAM password-protected data set identified by the 
unique DDname provided in the JCL. The operator will also be required to 
provide the catalog master password or the data set master password for each 
VSAM password-protected data set. 

• D14STEP2, during this job step the operator will be required to provide the 
password for each non-VSAM password-protected data set residing on the 
receiving volume. A DD statement need not be provided for those non-VSAM 
data sets. The operator will also be required to provide the catalog master 
password or the data set master password for each VSAM password-protected 
data set. 

If the tape data set is password protected, its password must also be supplied,, 
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IEHINITT Program 



iehinitt is a system utility used to place IBM volume label sets written in 
EBCDIC, in BCD, or in ASCII (American Standard Code for Information 
Interchange) onto any number of magnetic tapes mounted on one or more tape 
units. (See "Introduction" for general system utility information.) Because 
IEHINITT can overwrite previously labeled tapes regardless of expiration date and 
security protection, it is suggested that IEHINITT be moved and deleted from 
SYS1.LINKLIB into an authorized password protected private library. Each volume 
label set created by the program contains: 

• A standard volume label with user specified serial number and owner 
identification. 

• An 80-byte dummy header label. For IBM standard labels, this record consists 
of HDRl followed by zeros. For labels written in ASCII, this record consists of 
HDRl followed by zeros in the remaining positions, with the exception of 
position 54, which contains an ASCII space. 

• A tapemark. 

Note: When a labeled tape is subsequently used as a receiving volume: (1) the 
tape mark created by IEHINITT is overwritten, (2) the dummy HDRl record 
created by IEHINITT is filled in with operating system data and device-dependent 
information, (3) a HDR2 record, containing data set characteristics, is created, (4) 
user header labels are written if exits to user label routines are provided, (5) a 
tapemark is written, and (6) data is placed on the receiving volume. 

Figure 16-1 shows an IBM standard label group after a volume is used to receive 
data. Refer to OS/VS Data Management Services Guide, GC26-3783, for a 
discussion of volume labels. 



Initial volume label 



HDR2 



User header labels 
(optional up to 8) 



Tape mark 



Data 



Figure 16-1. IBM Standard Label Group After Volume Receives Data 

Placing a Standard Label Set on Magnetic Tape 

IEHINITT can be used to write BCD labels on 7 -track tape volumes and EBCDIC 
or ASCII labels on 9-track tape volumes. Any number of 7-track and/or 9-track 
tape volumes can be labeled in a single execution of IEHINITT. 

Tape volumes are labeled in sequential order by specifying a serial number to be 
written on the first tape volume. The serial number is incremented by 1 for each 
successive tape volume. If only one tape volume is to be labeled, the specified 
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Input and Output 



Control 



serial number can be either numeric or alphameric. If more than one volume is to 
be labeled, the serial numbers must be specified as six numeric characters. 

The user can provide additional information, such as owner name, rewind or 
unload specifications, and whether the label is to be written in ASCII. 

The user must supply all tapes to be labeled, and must include with each job 
request explicit instructions to the operator about where each tape is to be 
mounted. 

If any errors are encountered while attempting to label a tape, the tape is left 
unlabeled. IEHINITT attempts to label any tapes remaining to be processed. 

For information on creating routines to write standard or non-standard labels, 
refer to OS/VS Tape Labels, GC26-3795. 

IEHINITT writes 7-track tape labels in even parity (translator on, converter off). 

Previously labeled tapes can be overwritten with new labels regardless of 
expiration date and security protection. 



IEHINITT uses as input a control data set that contains the utility control 
statements. 

IEHINITT produces an output data set that contains: (1) utility program 
identification, (2) initial volume label information for each successfully labeled 
tape volume, (3) contents of utility control statements, and (4) any error 
messages. 

IEHINITT produces a return code to indicate the results of program execution. 
The return codes and their meanings are: 

• 00, which indicates successful completion. A message data set was created. 

• 04, which indicates successful completion. No message data set was defined by 
the user. 

• 08, which indicates that the program completed its operation, but error 
conditions were encountered during processing. A message data set was 
created. 

• 12, which indicates that the program completed its operation, but error 
conditions were encountered during processing. No message data set was 
defined by the user. 

• 16, which indicates that the program terminated operation because of error 
conditions encountered while attempting to read the control data set. A 
message data set was created if defined by the user. 



iehinitt is controlled by job control statements and utility control statements. 
The job control statements are used to execute or invoke IEHINITT and to define 
data sets used and produced by IEHINITT. Utility control statements are used to 
specify applicable label information. 



Job Control Statements 



Table 16-1 shows the job control statements necessary for using IEHINITT. 
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Restrictions 



Table 16-1. iehinitt Job Control Statements 

Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (PGM=IEHINITT) or, if the job control 

statements reside in a procedure library, the procedure name. The exec 
statement can include additional parm information; see "parm 
Information on the exec Statement." 

SYSPRINT DD Defines a sequential output data set. 

anyname DD Defines a tape unit to be used in a labeling operation; more than one tape 

unit can be identified. 

SYSIN DD Defines the control data set. The control data set normally resides in the 

input stream; however, it can be defined as a member of a partitioned data 
set or as a sequential data set outside the input stream. 

The "anyname" DD statement is entered: 

//anyname DD DCB=DEN=x,UNIT=(xxxx,n,DEFER) 

The DEN parameter specifies the density at which the labels are written. The 
UNIT parameter specifies the device type, number of units to be used for the 
labeling operation, and deferred mounting. The name "anyname" must be 
identical to a name specified in a utility control statement to relate the specified 
unit(s) to the appropriate utility control statement. 



• The SYSPRINT data set must have a logical record length of 121 bytes. It must 
consist of fixed length records with an ASA control character in the first byte 
of each record. Any blocking factor can be specified. 

• The SYSIN data set must have a logical record length of 80. Any blocking 
factor can be specified. 

• Labels written in ASCII cannot be put on 7-track tape volumes. 

PARM Information on the EXEC Statement 

The EXEC statement can include PARM information that specifies the number of 
lines to be printed between headings in the message data set, as follows: 

PARM=LINECNT=nn 

If PARM is omitted, 60 lines are printed between headings. 

If IEHINITT is invoked, the line count option can be passed in a parameter list 
that is referred to by the "optionaddr" subparameter of the LINK or ATTACH 
macro instruction. In addition, a page count can be passed in a six-byte 
parameter list that is referred to by the "hdingaddr" subparameter of the LINK or 
ATTACH macro instruction. For a discussion of linkage conventions, refer to 
"Appendix B: Invoking Utility Programs from a Problem Program." 

Utility Control Statement 

IEHINITT uses a utility control statement to provide control information for a 
labeling operation. 



IN ITT Statement 



The INITT statement provides control information for the IEHINITT program, 

Any number of INITT utility control statements can be included for a given 
execution of the program. An identically named DD statement must exist for a 
utility control statement in the job step. 
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The format of the INITT statement is: 
name INITT SER=xxxxxx 



[,OWNER='cccccccccc[cccc]'] 
[,NUMBTAPE=n] 
,DISP= {REWIND} 
{ UNLOAD } 
[,LABTYPE=AL] 



where: 



name 

specifies a name that is identical to a ddname in the name field of a DD 
statement defining a tape unit(s). This name must begin in column 1. 

SER=xxxxxx 

specifies the volume serial number of the first or only tape to be labeled. The 
serial number cannot contain blanks, commas, apostrophes, equal signs, or 
special characters other than periods or hyphens. A specified serial number is 
incremented by one for each additional tape to be labeled. (Serial number 
999999 is incremented to 000000.) When processing multiple tapes, the 
volume serial number must be all numeric. 

OWNER = *cccccccccc[cccc]' 

specifies the owner's name or similar identification. The information is 
specified as character constants, and can be up to 10 bytes in length for 
EBCDIC and BCD volume labels, or up to 14 bytes in length for volume labels 
written in ASCII. The delimiting apostrophes can be omitted if no blanks, 
commas, apostrophes, equal signs, or other special characters (except periods 
or hyphens) are included. If an apostrophe is included, it must be written as 
two consecutive apostrophes. 

NUMBTAPE=n 

specifies the number of tapes to be labeled according to the specifications 
made in this control statement. The value n represents a number from 1 to 
255. If NUMBTAPE is omitted, one tape volume is labeled. If more than one 
tape is specified, the serial number must be numeric. 

DISP= 

specifies whether a tape is to be rewound or unloaded. These values can be 
coded: 

REWIND 

specifies that a tape is to be rewound (but not unloaded) after the label has 
been written. If DISP=REWIND is not specified, the tape volume is rewound 
and unloaded. 

UNLOAD 

specifies that a tape is to be unloaded after the label has been written. This 
is the default. 

LABTYPE=AL 

specifies that a volume label written in ASCII is to be created. If LABTYPE is 
not specified, the tape is written in EBCDIC for 9-track tape volumes and in 
BCD for 7-track tape volumes. 
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IEHINITT Examples 



Figure 16-2 shows a printout of a message data set including the INITT statement 
and initial volume label information. In this example, one INITT statement was 
used to place serial numbers 001 122 -and 001123 on two tape volumes. VOL10011220 
and VOL10011230 are interpreted, as follows: 

• VOLl indicates that an initial volume label was successfully written to a tape 
volume. 

• 001122 and 001123 are the serial numbers that were written onto the volumes. 

• is the Volume Security field. 

No errors occurred during processing. 



SYSTEM SUPPORT UTILITIES IEHINITT 

ALL INITT SER=001 122, NUMBTAPE=2 , OWNER= ' P.T.BROWN 1 , 
DISP=REWIND 



72 
C 



VOL1001 1220 
VOL1001 1230 



P . T . BROWN 
P . T . BROWN 



Figure 16-2. Printout of INITT Statement Specifications and Initial Volume Label! 
Information 



The following examples illustrate some of the uses of IEHINITT. Table 16-2 can 
be used as a quick reference guide to IEHINITT examples. The numbers in the 
"Example" column point to examples that follow. 

Table 16-2. iehinitt Example Directory 

Operation Comments Example 

LABEL Three 9-track tapes are to be labeled. 1 

LABEL A 9-track tape is to be labeled. 2 

LABEL Two groups of 9-track tape volumes are to be labeled. 3 

LABEL 9-track tape volumes are to be labeled. Sequence 

numbers are to be incremented by 10. 4 

LABEL Three 9-track tape volumes are to be labeled. An 

alphameric label is to be placed on a 2400 volume; 
numeric labels are placed on the 2400-4 volumes. 5 

LABEL Two 9-track tape volumes are to be labeled. The 

first volume is labeled at a density of 6250 bpi; 
the second at a density of 1600 bpi. 6 



IEHINITT Example 1 



In this example, serial numbers 001234, 001235, and 001236 are to be placed on 
three tape volumes; the labels are to be written in EBCDIC at 800 bits per inch. 
Each volume to be labeled is mounted, when it is required, on a single 9-track 
tape unit. 

The example follows: 



//LABEL 1 
// 

//SYSPRINT DD 
//LABEL DD 
//SYSIN DD 
LABEL INITT 
/* 



JOB 09 #990, BROWN, MSGLEVEL=( 1,1) 
EXEC PGM=IEHINITT 

SYSOUT=A 

DCB=DEN=2,UNIT=( 2400, 1 , DEFER) 

* 

SER=001234,NUMBTAPE=3 
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IEHIMITT Example 2 



IEHINITT Example 3 



IEHINITT Example 4 



In this example, serial number 001001 is to be placed on one ASCII tape volume; 
the label is to be written at 800 bits per inch. The volume to be labeled is 
mounted, when it is required, on a 9-track tape unit. 

The example follows: 



//LABEL2 

// 

//SYSPRINT DD 

//ASCI I LAB DD 

//SYSIN DD 

ASCIILAB INITT 

/* 



JOB 09# 990, BROWN, MSGLEVEL=( 1,1) 
EXEC PGM=IEHINITT 



SYSOUT=A 

DCB=DEN=2 , UNIT=( 2400 , 1 , DEFER ) 

SER=00 1001, OWNER= ' SAM A . BROWN ' , LABTYPE=AL 



In this example, two groups of serial numbers (001234, 001235, 001236, and 
001334, 001335, 001336) are placed on six tape volumes. The labels are to be 
written in EBCDIC at 800 bits per inch. Each volume to be labeled is mounted, 
when it is required, on a single 9-track tape unit. 

The example follows: 



//LABEL3 

// 

//SYSPRINT DD 
//LABEL DD 
//SYSIN DD 
LABEL INITT 
LABEL INITT 
/* 



JOB 09#990, BROWN, MSGLEVEL=( 1,1) 
EXEC PGM=IEHINITT 

SYSOUT=A 

DCB=DEN=2 , UNIT=( 2400 , 1 , DEFER ) 

* 

SER=00 1234, NUMBTAPE=3 
SER=00 1334, NUMBTAPE=3 



In this example, serial numbers 001234, 001244, 001254, 001264, 001274, etc., 
are to be placed on eight tape volumes. The labels are to be written in EBCDIC at 
800 bits per inch. Each volume to be labeled is mounted, when it is required, on 
one of four 9-track tape units. 



The example follows: 



//LABEL4 JOB 


// 


EXEC 


//SYSPRINT DD 


//LABEL 


DD 


//SYSIN 


DD 


LABEL 


INITT 


LABEL 


INITT 


LABEL 


INITT 


LABEL 


INITT 


LABEL 


INITT 


LABEL 


INITT 


LABEL 


INITT 


LABEL 


INITT 


/* 





09#990, BROWN, MSGLEVEL=( 1,1) 

PGM=IEHINITT 

SYSOUT=A 

DCB=DEN=2 , UNIT=( 2400 , 4 , DEFER ) 

* 

SER=001234 
SER=001244 
SER=001254 
SER=001264 
SER=001274 
SER=001284 
SER=001294 
SER=001304 
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IEHINITT Example 5 



IEHINITT Example 6 



In this example, serial number TAPEl is to be placed on a 2400 tape unit, and 
serial numbers 001234 and 001235 are to be placed on two 2400-4 tape units. 
The labels are to be written in EBCDIC at 800 and 1600 bits per inch. 

The example follows: 

//LABEL5 JOB 09#990 , BROWN, MSGLEVEL=( 1 , 1 ) 

// EXEC PGM=IEHINITT 

//SYSPRINT DD SYSOUT=A 

DCB=DEN=2 , UNIT=( 2400 , 1 , DEFER ) 
DCB=DEN=3 , UNIT=( 2400-4 , 1 , DEFER ) 
* 

SER=TAPE1 

SER=00 1234, NUMBTAPE=2 



//LABEL 1 DD 
//LABEL2 DD 
//SYSIN DD 
LABEL 1 INITT 
LABEL2 INITT 
/* 



Note: If 2400 tape units are not available for allocation and the system 
configuration includes 3400 tape units, a 3400 tape unit may be allocated by 
default. 



In this example, the serial number 006250 is to be written in EBCDIC on a tape 
volume at a density of 6250 bpi, and the serial number 001600 is to be written 
in EBCDIC on a second volume at a density of 1600 bpi. The DDFIRST DD 
statement identifies a single density (6250 bpi only) 3420 tape drive. The 
DDSECOND DD statement identifies a dual density (6250/1600 bpi) 3420 tape 
drive. 



The example follows: 



//LABEL6 JOB 


09 #990, BROWN, MSGLEVEL=( 1,1) 


// EXEC 


PGM=IEHINITT 


//SYSPRINT DD 


SYSOUT=A 


//DDFIRST DD 


DCB=DEN=4 , UNIT=( 3400-5 , 1 , DEFER ) 


//DDSECOND DD 


DCB=DEN=3 , UNIT=( 3400-6 , 1 , DEFER ) 


//SYSIN DD 


* 


DDFIRST INITT 


SER=006250 


DDSECOND INITT 


SER=001600 


/* 
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IEHIOSUP Program (VS1 Only) 



Input and Output 



Control 



IEHIOSUP is a system utility (VSl only — not supported under VS2) used to update 
TTR entries in the transfer control tables of the supervisor call library (SVC 
library). (See "Introduction" for general system utility information.) Because of 
the way SVC routines are loaded, it is necessary to update TTR entries after 
changing or replacing a module. IEHIOSUP automatically updates the TTR entries. 
IEHIOSUP must be used after: 

• The SVC library is moved. 

• The OPEN, CLOSE, TCLOSE, EOV, FEOV, SCRATCH, ALLOCATE, IEHATLAS, 
SETPRT, STOW, or any Machine Check Handler (MCH) recovery management 
module is changed or replaced in the SVC library. 



IEHIOSUP uses as input an object data set SYS1.SVCLIB) that contains the transfer 
control tables that are to be updated. 

IEHIOSUP produces as output a message data set that contains any error messages 
generated during the execution of the program. 

IEHIOSUP produces a return code to indicate the results of program execution. 
The return codes and their interpretations are: 

• 00, which indicates successful completion. 

• 12, which indicates an unrecoverable error. The job step is terminated. 



IEHIOSUP is executed or invoked with job control statements. No utility control 
statements are required. 



Job Control Statements 



Table 17-1 shows the job control statements necessary for using IEHIOSUP. 



Table 17-1. 

Statement 

JOB 

EXEC 

SYSPRINT DD 
SYSUT1 DD 



iehiosup Job Control Statements 

Use 

Initiates the job. 

Specifies the program name (PGM-iehiosup) or, if the job control 
statements reside in a procedure library, the procedure name. 



Defines a sequential message data set. 

Defines the object data set (SYSI.SVCLIB). The DSNAME, DISP, unit, and 
VOLUME parameters should be included. 

If the SYSI.SVCLIB data set is cataloged, the UNIT and VOLUME parameters are 
not required on the SYSUTl DD statement. 



Restrictions 



The block size for the SYSPRINT data set must be a multiple of 121. Any 
blocking factor can be specified. 



IEHIOSUP Program (VSl Only) 17-1 



IEHIOSUP Examples 



The following examples illustrate some of the uses of IEHIOSUP. Table 17-2 can 
be used as a quick reference guide to IEHIOSUP examples. The numbers in the 
"Example" column point to examples that follow. 

Table 17-2. IEHIOSUP Example Directory 

Data Set 
Operation Organization Device Comments Example 

UPDATE Partitioned, 2314 Disk, SVC library is to be updated. 

Sequential system output SYS1.SVCLIB is not cataloged. 

device System output device is a printer. 1 

UPDATE Partitioned, 3330 Disk, SVC library is to be updated. 

Sequential system output SYS1.SVCLIB is cataloged. System 

device output device is a printer. 2 



IEHIOSUP Example 1 



IEHIOSUP Example 2 



In this example, the TTR entries in the SVC library are to be updated. 
The example follows: 

//TTRUPDTE JOB 

// EXEC PGM=IEHIOSUP 

//SYSUT1 DD DSNAME=SYS1 . SVCLIB,DISP=OLD, UNIT==23 1 4 , 

// VOLUME=SER=1 11111 

//SYSPRINT DD SYSOUT=A 

/* 

The control statements are discussed below: 

• sysuti dd defines the object data set (the sysi.svclib data set). 

• SYSPRINT DD defines the message data set. 



In this example, the TTR entries in the SVC library are to be updated. 

The example follows: 

//SVCUPDTE JOB 

// EXEC PGM=IEHIOSUP 

//SYSUT1 DD DSNAME=SYS1 . SVCLIB, DISP=OLD 

//SYSPRINT DD SYSOUT=A 

/* 

The control statements are discussed below: 

• SYSUTI DD defines the object data set (the SYSI.SVCLIB data set). Because the 
data set is cataloged, UNIT and VOLUME parameters are not required. 

• SYSPRINT DD defines the message data set. 
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IEHLIST Program for VS1 Release 3 



Listing Catalog Entries 



IEHLIST is a system utility used to list entries in a catalog, entries in the directory 
of one or more partitioned data sets, or entries in a volume table of contents. 
(See "Introduction" for general system utility information.) Any number of 
listings can be requested in a single job. 



IEHLIST lists all catalog entries that are part of the structure of a fully-qualified, 
data set name. Figure 18-1 shows an index structure for which IEHLIST lists 
fully-qualified names A.B.D.W, A.B.D.X, A.B.E.Y, and A.B.E.Z. Because A.C.F does 
not represent a cataloged data set (that is, the lowest level of qualification has 
been deleted), it is not a fully-qualified name, and it is not listed. 



W X Y Z 

Figure 18-1. Index Structure — Listed by iehlist 

Listing a Partitioned Data Set Directory 

IEHLIST can list up to ten partitioned data set directories in a single application 
of the program. A partitioned directory is composed of variable length records 
blocked into 256-byte blocks. Each directory block can contain one or more 
entries which reflect member (and/or alias) names and other attributes of the 
partitioned members in edited and unedited format. 

Figure 18-2 shows a directory block as it exists in storage. 

















Member A 


TTR 


User data 


Member B 


TTR 


User 


Data 


Member C 


TTR 


User data 


Member n 



































Edited Format 



Figure 18-2. Sample Directory Block 



IEHLIST optionally provides the following information, which is obtained from 
the applicable partitioned data set directory, when an edited format is requested: 

• Member name 

• Entry point 
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OS linkage editor attributes 
Relative address of start of member 
Relative address of start of text 
Contiguous main storage requirements 
Length of first block of text 
Origin of first block of text 
System status indicators 
OS/VS linkage editor attributes 
apf authorization required 
Other information 



Before printing the directory entries on the first page, an index is printed 
explaining the asterisk (*), if any, following a member name, the attributes (fields 
3 and 10), and other information (field 12). Under the OTHER INFORMATION 
INDEX, scatter and overlay format data is described positionally as it appears in 
the listing; under the ATTRIBUTE INDEX, the meaning of each attribute bit is 
explained. 

Each directory entry occupies one printed line, except when the member name is 
an alias and the main member name and associated entry point appear in the 
user data field. When this occurs, two lines are used and every alias is followed 
by an asterisk. 

Note: The FORMAT option applies only to a partitioned data set whose members 
have been created by the linkage editor (that is, the directory entries are at least 
34 bytes long). If a directory entry is less than 34 bytes, a message is issued and 
the entry is printed in unedited format; if the entry is longer than 34 bytes, it is 
assumed that it is created by the linkage editor. 

Figure 18-3 shows an edited entry for a partitioned member (IEANUCOD. The 
entry is shown as it is listed by the IEHLIST program. 

OTHER INFORMATION INDEX 
SCATTER FORMAT SCTR=SCATTER/TRANSLATION TABLE TTR IN HEX, LEN OF SCRT LIST IN DEC, LEN OF TRANS TABLE IN DEC, 
ESDID OF FIRST TEXT RCD IN DEC, ESDID OF C3ECT CONTAINING ENTRY POINT IN DEC 



OVERLAY FORMAT 
ALIAS NAMES 



BIT 




ON 

RENT 
REUS 
ONLY 
TEST 



ONLY=NOTE LIST RCD TTR IN HEX, NUMBER OF ENTRIES IN NOTE LIST RCD IN DEC 
ALIAS MEMBER NAMES WILL BE FOLLOWED BY AN ASTERISK IN THE PDS FORMAT LISTING 

ATTRIBUTE INDEX 
OFF BIT ON OFF BIT ON 



MEMBER 
NAME 



NOT RENT 
NOT REUS 
NOT ONLY 
NOT TEST 

ATTR 
HEX 



ENTRY 
PT-HEX 

000000 06E2 



BIT 
4 
5 
6 
7 

REL 
BEGIN 



OL 
SCTR 
EXEC 
1 TXT 



OFF 

NOT OL 
BLOCK 
NOT EXEC 
MULTI RCD 



ADDR-HEX 
1ST TXT 



CONTIG 
STOR-DEC 

000166248 0927 



NOT DC 
ZERO ORG 
' EP ZERO 
NO RLD 

LEN 1ST 
TXT-DEC 



OFF 

DC 

NOT ZERO 

NOT ZERO 

RLD 



BIT 

12 
13 
14 
15 



ORB 1ST 
TXT-HEX 



SSI 
INFO 



NOT EDIT 

SYMS 

F LEVEL 

REFR 

VS 
ATTR 

880000 



OFF 

EDIT 
NO SYMS 
E LEVEL 
NOT REFR 



AUTH 
REQ 



OTHER 
INFORMATION 

SCTR=000000, 
00484,01084,32,32 



OF THE 00002 DIRECTORY BLOCKS ALLOCATED TO THIS PDS, 00001 ARE (IS) COMPLETELY UNUSED 

Figure 18-3. Edited Partitioned Directory Entry 



Unedited (Dump) Format 



The user may choose the unedited format. If this is the case, IEHLIST lists each 
member separately. 

Figure 18-4 shows how the information in Figure 18-2 is listed. 

Note: A listing organized as shown in Figure 18-4 can also be obtained by using 
IEBPTPCH (see "IEHPTPCH Program "). 
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MEMB A TTR 

MEMB B TTR 

MEMB C TTR 

MEMB n TTR 



USER DATA 
USER DATA 
USER DATA 
USER DATA 



Figure 18-4. Sample Partitioned Directory Listing 



To correctly interpret user data information, the user must know the format of 
the partitioned entry. The formats of directory entries are discussed in 0S/VS1 
System Data Areas, SY28-0605, and 0S/VS2 System Data Areas, SY28-0606. 



Listing a Volume Table of Contents 

IEHLIST can be used to list, partially or completely, entries in a specified volume 
table of contents (VTOC). The program lists the contents of selected data set 
control blocks (DSCBs) in edited or unedited form. 



Edited Format 



Two edited formats are available. One is a comprehensive listing of the DSCBs in 
the VTOC. It provides the status and attributes of the volume, and describes in 
depth the data sets residing on the volume. This listing includes: 

Logical record length and block size 

Initial and secondary allocations 

Upper and lower limits of extents 

Alternate track information 

Available space information, in detail 

Option codes 

Record formats 

A VTOC consists of as many as seven types of DSCBs which contain information 
about the data sets residing on the volume: 

Identifier DSCB — Format 1 

Index DSCB — Format 2 

Extension DSCB — Format 3 

VTOC DSCB — Format 4 

Free Space DSCB — Format 5 

Shared Extent DSCB — Format 6 

Free VTOC DSCB — Format 

The first DSCB in a VTOC (and on your listing) is always a VTOC (Format 4) 
DSCB. It defines the scope of the VTOC itself; that is, it contains information 
about the VTOC and the volume rather than the data sets referenced by the 

VTOC. 

The VTOC (Format 4) DSCB is followed, when necessary, by the Free Space 
(Format 5) DSCB, which describes the space available on the volume for 
allocation to other data sets. More than one Format 5 DSCB may be required to 
describe the available space on a volume because each Format 5 DSCB describes 
only 26 extents. 

The Format 4 and Format 5 DSCBs are followed, in any order, by Format 1, 2, 
3, or 6 DSCBs. 
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Each Identifier (Format 1) DSCB contains information about a particular data set 
residing on the volume. This type of DSCB describes the characteristics and up to 
three extents of the data set. 

For data sets having indexed sequential organization, additional characteristics 
are specified in an Index (Format 2) DSCB pointed to by the Identifier (Format 
1) DSCB. 

Additional extents are described in an Extension (Format 3) DSCB pointed to by 
the Identifier (Format 1) DSCB or in the Index (Format 2) DSCB for an 
indexed-sequential data set. 

A Shared Eixtent (Format 6) DSCB is used for shared-cylinder allocation. It 
describes the extent of space (one or more contiguous cylinders) that is being 
shared by two or more data sets. The Shared Extent (Format 6) DSCB is pointed 
to by the VTOC (Format 4) DSCB. Subsequent Format 6 DSCBs are pointed to by 
the previous Format 6 DSCB. 

A Free VTOC Record (Format 0) DSCB, which indicates space available for 
another DSCB, is not listed by IEHLIST. They are 140-byte records, consisting of 
binary zeros, that are overwritten with Format 1, 2, 3, and 6 DSCBs when a new 
data set is allocated, and with Format 5 DSCBs when space is released. 

Figure 18-5 shows a sample listing of the edited format. This sample illustrates 
how each DSCB will appear on a listing, although in many cases the VTOC may 
not contain all possible types. The information is in columns, with the values or 
numbers appearing underneath each item's heading. 



SYSTEMS SUPPORT UTILITIES IEHLIST 



CONTENTS OF VTOC ON VOL EXAMPL 

FORMAT 4 DSCB NO AVAIL/MAX DSCB /MAX DIRECT NO AVAIL NEXT ALT 
DSCBS PER TRK BLK PER TRK ALT TRK TRK(C-H) 
154 16 10 10 200 



FORMAT 6 LAST FMT 1 VTOC EXTENT THIS DSCB 
(C-H-R) DSCB(C-H-R)/LOW(C-H) HIGH! C-H ) ( C-H-R ) 



FORMAT 5 DSCB 

TRK FULL 
ADDR CYLS 



A = NUMBER OF TRKS IN ADDITION TO FULL CYLS IN THE EXTENT 



TRK 

ADDR 

110 



FULL 

CYLS 

189 



DSCB( C-H-R) 



USED PDS BYTES FMT 2 OR 3( C-H-R )/DSCB( C-H-R ) 
5 3 5 4 

EXTENTS NO LOW( C-H ) HIGH! C-H ) 
6 10 9 

2MINDI M-B-C-H )/3MIND( M-B-C-H )/L2MFN( C-H-R )/L3MIN( C-H-R )/CYLAD( M-B-C-H )/ADLIN( M-B-C-H )/ADHIN( M-B-C-H 1/NOBYT/ NOTRK 
0000 0000 000 000 10109 0000 10109 70 

LTRADI C-H-R )/LCYAD( C-H-R )/LMSAD( C-H-R )/LPRAD( M-B-C-H-R ) /NOLFV /CYLOV/ TAGDT/ PRCTR / OVRCT/ RORG1/PTRDSI C-H-R ) 
603 10 91000 1061 12 1 20 
UNABLE TO CALCULATE EMPTY SPACE. 



DSORG RECFM OPTCD 



USED PDS BYTES FMT 2 OR 3( C-H-R )/DSCB( C-H-R ) 



EXTENTS NO LOW( C-H 1 



NO LOW C-H) HIGH! C-H) NO LOW C-H ) HIGH! C-H ) 



-ON THE ABOVE DATA SET, THERE ARE EMPTY TRACK! S ) . 



192 EMPTY CYLINDERS PLUS 3 EMPTY BRACKS ON THIS VOLUME 
154 BLANK DSCBS IN THE VTOC ON THIS VOLUME 



Figure 18-5. Sample Printout of a Volume Table of Contents 
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Unedited (Dump) Format 



Input and Output 



Control 



The second edited format is an abbreviated description of the data sets. It is 
provided by default when no format is requested specifically. It provides the 
following information: 

Data set name 

Creation date (dddyy) 

Expiration date (dddyy) 

Password indication 

Organization of the data set 

Extent(s) 

Volume serial number 

The last line in the listing indicates how much space remains in the VTOC. 



This option produces a complete hexadecimal listing of the DSCBs in the VTOC 
The listing is in an unedited dump form, requiring the user to know the various 
formats of applicable DSCBs. The VTOC overlay for IEHLIST listings of VTOCs in 
dump format (Order Number ZM08-0033) is useful in identifying the fields of 
the DSCBs. 

Refer to 0S/VS1 System Data Areas, SY28-0605, or 0S/VS2 System Data Areas, 
SY28-0606, for a discussion of the various formats that data set control blocks 
can assume. 



IEHLIST uses the following input: 

• One or more source data sets that contain the data to be listed. The input data 
set(s) can be: (1) a VTOC data set, (2) a partitioned data set, or (3) a catalog 
data set (SYSCTLG). 

• A control data set, which contains utility control statements that are used to 
control the functions of IEHLIST. 

IEHLIST produces as output a message data set, which contains the result of the 
IEHLIST operations. The message data set includes the listed data and any error 
messages. 

IEHLIST produces a return code to indicate the results of program execution. The 
return codes and their meanings are: 

• 00, which indicates successful completion. 

• 08, which indicates that an error condition caused a specified request to be 
ignored. Processing continues. 

• 12, which indicates that a permanent input/ output error occurred. The job is 
terminated. 

• 16, which indicates that an unrecoverable error occurred while reading the 
data set. The job is terminated. 



IEHLIST is controlled by job control statements and utility control statements. 
The job control statements are used to execute or invoke IEHLIST and to define 
the data sets used and produced by IEHLIST. 



IEHLIST Program for VS1 Release 3 1 8-5 



Utility control statements are used to control the functions of the program and to 
define those data sets or volumes to be modified. 



Job Control Statements 



Table 18-1 shows the job control statements necessary for using IEHLIST. 
Table 18-1. iehlist Job Control Statements 



Statement 

JOB 

EXEC 



Use 

Initiates the job. 



Specifies the program name (PGM=IEHLIST) or, if the job control statements 
reside in a procedure library, the procedure name. Additional PARM 
information can be specified to control the number of lines printed per 
page. See "PARM Information on the EXEC Statement" below. 

SYSPRINT DD Defines a sequential message data set. 

anynamel DD Defines a permanently mounted volume. 

anyname2 DD Defines a mountable device type. 

SYSIN DD Defines the control data set. The control data set normally follows the job 

control language in the input stream; however, it can be defined as an 
unblocked sequential data set or member of a procedure library. 

The "anynamel" DD statement can be entered: 

//anynamel DD UNIT=xxxx,VOLUME=SER=xxxxxx,DISP=OLD 

The UNIT and VOLUME parameters define the device type and volume serial 
number. The DISP=OLD specification prevents the inadvertent deletion of the 
data set. This statement is arbitrarily assigned the ddname DDl in the IEHLIST 
examples. 

When deferred mounting is required, the "anyname2" DD statement can be 
entered: 

//anyname2 DD UNIT=(xxxx„DEFER),VOLUME=(PRIVATE,...),DISP=OLD 

See "Appendix C: DD Statements for Defining Mountable Devices" for 
information on defining mountable devices. This statement is arbitrarily assigned 
the ddname DD2 in the IEHLIST examples. Statements defining additional 
mountable devices are assigned ddnames DD3, DD4, etc. 

With the exception of the SYSIN and SYSPRINT DD statements, all DD statements 
in this table are used as device allocation statements, rather than as true data 
definition statements. 



Restrictions 



The block size for the SYSPRINT data set must be a multiple of 121. The 
block size for the SYSIN data set must be a multiple of 80. Any blocking 
factor can be specified for these block sizes. 

An "anynamel" DD statement must be included for each permanently 
mounted volume referred to in the job step. (The system residence volume is 
considered to be a permanently mounted volume.) 

An "anyname2" DD statement must be included for each mountable device to 
be used in the job step. 

Because IEHLIST modifies the internal control blocks created by device 
allocation DD statements, IEHLIST job control statements must not include the 
DSNAME parameter. (All data sets are defined explicitly or implicitly by utility 
control statements.) 

When IEHLIST is dynamically invoked in a job step containing another 
program, the DD statements defining mountable devices for IEHLIST must be 
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included in the job stream prior to DD statements defining data sets required 
by the other program. 

• IEHLIST cannot support empty space calculations for data sets allocated in 
blocks when the block sizes are approximately the same or larger than the 
track size. The empty block calculation gives only approximate indications of 
available space. When IEHLIST cannot supply an approximate number, the 
"Unable ,to Calculate" message is issued. 

• IEHLIST specifications do not allow for protection of the object being listed. If 
another program updates a block of the data set just prior to IEHLIST reading 
the data set, a message (IEH105I or IEH108I) may be issued. In the case of 
LISTVTOC, the output produced by IEHLIST may be incorrect. When this 
happens, you should rerun the job. 



PARM Information on the EXEC Statement 

Additional information can be specified in the PARM parameter of the EXEC 
statement to control the number of lines printed per page. The PARM parameter 
can be coded: 

PARM='LINECNT=xx' 

The LINECNT parameter specifies the number of lines, xx, to be printed per 
page; xx is a decimal number from 01 through 99. If LINECNT is not specified, 
58 lines are printed per page. The PARM field cannot contain embedded blanks, 
zeros, or any other PARM keywords, or the default of 58 is used. 

Utility Control Statements 

IEHLIST is controlled by the following utility control statements: 

• LISTCTLG statement, which is used to request a listing of all or part of a 
catalog. 

• LISTPDS statement, which is used to request a directory listing of one or more 
partitioned data sets. 

• LISTVTOC statement, which is used to request a listing of all or part of a 
volume table of contents. 



LISTCTLG Statement 



The LISTCTLG statement is used to request a listing of either the entire catalog 
or a specified portion of the catalog (SYSCTLG data set). The listing includes the 
fully-qualified name of each applicable cataloged data set and the serial number 
of the volume on which it resides. Empty index levels are not listed. 

The format of the LISTCTLG statement is: 

[label] LISTCTLG [VOL=dewce= serial] 
[,NODE= name] 

where: 

VOL = device = serial 

specifies the device type and volume serial number of the control volume on 
which the specified portion of the catalog resides. If VOL is omitted, the 
catalog is assumed to reside on the system residence volume. 

NODE= name 

specifies a qualified name. All data set entries whose names are qualified by 
this name are listed. If NODE is omitted, all data set entries are listed. 

Note: General catalog information (one-level data sets, alias entries, and CVOL 
pointers) is printed prior to the printing of an entire catalog or node. 
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LISTPDS Statement 



LISTVTOC Statement 



The LISTPDS statement is used to request a directory listing of one or more 
partitioned data sets that reside on the same volume. 

The format of the LISTPDS statement is: 



[label] LISTPDS 



DSNAME = (name[,name] ...) 

[,VOL=dewce=ser/a/] 

{,DUMP} 

{,FORMAT} 



where: 



DSNAME == (name[,name] ...) 

specifies the fully qualified names of the partitioned data sets whose 
directories are to be listed. A maximum of ten names is allowed. If the list 
consists of a single name, the parentheses can be deleted. 

VOL = device = serial 

specifies the device type and volume serial number of the volume on which the 
partitioned data sets reside. If VOL is omitted, the data sets are assumed to 
reside on the system residence volume. 

DUMP 

specifies that the listing is to be in unedited, hexadecimal form. 

FORMAT 

specifies that the listing is to be edited for each directory entry. 

Before printing the directory entries on the first page, an index is printed 
explaining the attributes (fields 3 and 10) and other information (field 12). OTHER 
INFORMATION INDEX explains scatter and overlay format data as it appears in 
the listing; ATTRIBUTE INDEX explains each attribute bit. 

Note: The LISTPDS statement may be used only on a partitioned data set whose 
members have been created by the linkage editor. Members that have not been 
created by the linkage editor cause their directory entries to be listed in unedited 
(DUMP) format. 



The LISTVTOC statement is used to request a partial or complete listing of the 
entries in a specified volume table of contents. 

The format of the LISTVTOC statement is: 

[label] LISTVTOC {DUMP} 

{FORMAT} 

[,DATE=dddyy] 

[,VOL=dewce=ser/a/] 

[,DSNAME=(name[,name]...) 

where: 

DUMP 

specifies that the listing is to be in unedited, hexadecimal form. If both DUMP 
and FORMAT are omitted, an abbreviated edited format is generated by 
default. 

FORMAT 

specifies that a comprehensive edited listing is to be generated. If both 
FORMAT and DUMP are omitted, an abbreviated edited format is generated by 
default. 



18-8 OS/VS Utilities 



IEHLIST Examples 



IEHLIST Example 1 



DATE=dddyy 

specifies that each entry that expires before this date is to be flagged with an 
asterisk (*) in the listing. This parameter applies only to the abbreviated edited 
format. The date is represented by ddd, the day of the year, and yy, the last 
two digits of the year. If DATE is omitted, no asterisks appear in the listing. 

VOL=dev/ce=ser/a/ 

specifies the device type and volume serial number of the volume whose table 
of contents is to be listed. If VOL is omitted, the system residence volume is 
assumed. 

DSNAME=(name[,name]...) 

specifies the fully qualified names of the data sets whose entries are to be 
listed. A maximum of ten names is allowed. If DSNAME is omitted, the entire 
volume table of contents is listed. 



The following examples illustrate some of the uses of IEHLIST. Table 18-2 can be 
used as a quick reference guide to IEHLIST examples. The numbers in the 
"Example" column point to examples that follow. 



Table 18-2. iehlist Example Directory 

Operation Device Comments 



Example 



LIST 



LIST 



LIST 



LIST 



2314 Disk, 
system output 
device 

2314 Disk, 
system residence 
device, system 
output device 

2314 or 2319 
Disk, 1 3330 
Disk, system 
output device 

2314 Disk, 
system output 
device 



Source catalog is to be listed on the 
system output device. 

Three catalogs and part of a fourth 
are to be listed on the system 
output device. 

Three partitioned directories are to 
be listed on the system output device. 



Volume table of contents is to be 
listed in edited form; selected 
data set control blocks are listed 
in unedited form. 



1 Note that the 2319 disk is functionally equivalent to the 2314 disk; to use the 23 19, specify 
2314 in the control statement. 



Note: In the IEHLIST examples, the EXEC statement and the SYSPRINT DD 
statement can be replaced with the following job control statement: 

// EXEC PROC=LIST 

The EXEC statement invokes the following IBM-supplied cataloged procedure: 



//LIST EXEC 
//DDSRV DD 
//SYSPRINT DD 



PGM=IEHLIST,REGION=44K 

VOLUME=REF=SYSl.SVCLIB,DISP=OLD 

SYSOUT=A 



In this example a catalog residing on a 2314 volume (231400) is to be listed. 
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The example follows: 

//LISTCAT JOB 09#550,BLUE 

// EXEC PGM=IEHLIST 

//SYSPRINT DD SYSOUT=A 

//DD2 DD UNIT=2314,VOLUME=SER=231400,DISP=OLD 

//SYSIN DD * 

LISTCTLG VOL=23 14=23 1400 
/* 

The control statements are discussed below: 

• DD2 DD defines a mountable device on which the volume containing the 
source catalog is mounted. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• LISTCTLG defines the source volume and specifies the list operation. 
Note: The data set name of the catalog data set is SYSCTLG. 



IEHLIST Example 2 



In this example a catalog residing on the system residence volume, two catalogs 
residing on 2314 volumes, and a portion of a catalog residing on a 2314 volume, 
are to be listed. 

The example follows: 

//LISTCATS JOB 09#550,BLUE 

// EXEC PGM=IEHLIST 

//SYSPRINT DD SYSOUT=A 

//DD1 DD UNIT=3330,VOLUME=SER=1 1 1 1 1 1 ,DISP=OLD 

//DD2 DD UNIT=( 2314, , DEFER ),DISP=OLD, 

// VOLUME=( PRIVATE, ,SER=( 231400 ) ) 

//SYSIN DD * 



LISTCTLG 
LISTCTLG 
LISTCTLG 
LISTCTLG 



VOL=2314=231400 
VOL=2314=231401 
VOL=23 1 4=23 1 402 , NODE=A . B . C 



/* 



The control statements are discussed below: 

DDl DD defines a system residence device. (The first catalog to be listed 
resides on the system residence volume.) 

DD2 DD defines a mountable device on which each 2314 volume is mounted 
as it is required by the program. 

SYSIN DD defines the control data set, which follows in the input stream. 

The first LISTCTLG statement indicates that the catalog residing on the system 
residence volume is to be listed. 

The second and third LISTCTLG statements identify two 2314 disk volumes 
containing catalogs to be listed. 

The fourth LISTCTLG statement identifies a 2314 volume containing a catalog 
that is to be partially copied. All data set entries whose beginning qualifiers 
are "A.B.C" are copied. 



IEHLIST Example 3 



In this example, a partitioned directory existing on the system residence volume 
is to be listed. In addition, two partitioned directories existing on a 2314 or 2319 
volume are to be listed. 
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IEHLIST Example 4 



The example follows: 

//LISTPDIR JOB 09#550,BLUE 
// EXEC PGM=IEHLIST 

//SYSPRINT DD SYSOUT=A 

//DD1 DD UNIT=3330,VOLUME=SER=1 1 1 1 1 1 ,DISP=OLD 
//DD2 DD UNIT=2314,VOLUME=SER=231400,DISP=OLD 
* 

LISTPDS DSNAME=PARSET1 

LISTPDS DSNAME=( PART1 ,PART2 ) ,VOL=23 1 4=23 1 400 



//SYSIN DD 



/* 

The control statements are discussed below: 

• DD1 DD defines the system residence device. 

• DD2 DD defines a mountable device on which a 2314 volume (231400) is to 
be mounted. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• The first LISTPDS statement indicates that the partitioned data set directory 
belonging to data set PARSETl is to be listed. This data set exists on the 
system residence volume. 

• The second LISTPDS statement indicates that partitioned directories belonging 
to data sets PARTI and PART2 are to be listed. These data sets exist on a 2314 
volume (231400). 



In this example, a volume table of contents in edited form, is to be listed. The 
edited listing is supplemented by an unedited listing of selected data set control 
blocks. 

The example follows: 

//LISTVTOC JOB 09#550,BLUE 

// EXEC PGM=IEHLIST 

//SYSPRINT DD SYSOUT=A 

//DD2 DD UNIT=2314,VOLUME=SER=231400,DISP=OLD 

//SYSIN DD * 

LISTVTOC FORMAT, VOL=23 14=23 1400 

LISTVTOC DUMP, VOL=23 14=231 400, DSNAME=( SET 1 , SET2 , SET3 ) 
/* 

The control statements are discussed below: 

• DD2 DD defines a mountable device on which the volume containing the 
specified volume table of contents is to be mounted. 

• SYSIN DD defines the control data set which follows in the input stream. 

• The first LISTVTOC statement indicates that the volume table of contents on 
the specified 2314 volume is to be listed in edited form. 

• The second LISTVTOC statement indicates that the data set control blocks 
representing data sets SETl, SET2, and SET3 are to be listed in unedited form. 
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IEHLIST Program for VS2 Release 2 



IEHLIST is a system utility used to list entries in the directory of one or more 
partitioned data sets, or entries in a volume table of contents. (See 
"Introduction" for general system utility information.) Any number of listings 
can be requested in a single job. 

Listing a Partitioned Data Set Directory 

IEHLIST can list up to ten partitioned data set directories in a single application 
of the program. A partitioned directory is composed of variable length records 
blocked into 256-byte blocks. Each directory block can contain one or more 
entries which reflect member (and/or alias) names and other attributes of the 
partitioned members in edited and unedited format. 

Figure 19-1 shows a directory block as it exists in storage. 



Edited Format 





























f 


Member A 


TTR 


User data 


Member B 


TTR 


User 


Data 


Member C 


TTR 


User data 


Member n 




_ 





























Figure 19-1. Sample Directory Block 

EHLIST optionally provides the following information, which is obtained from 
he applicable partitioned data set directory, when an edited format is requested: 

Member name 

Entry point 

OS linkage editor attributes 
Relative address of start of member 
Relative address of start of text 
Contiguous main storage requirements 
Length of first block of text 
Origin of first block of text 
System status indicators 

OS/VS linkage editor attributes 

APF Authorization required 

Other information 

Before printing the directory entries on the first page, an index is printed 
explaining the asterisk (*), if any, following a member name, the attributes (fields 
3 and 10), and other information (field 12). Under the OTHER INFORMATION 
INDEX, scatter and overlay format data is described positionally as it appears in 
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the listing; under the ATTRIBUTE INDEX, the meaning of each attribute bit is 
explained. 

Each directory entry occupies one printed line, except when the member name is 
an alias and the main member name and associated entry point appear in the 
user data field. When this occurs, two lines are used and every alias is followed 
by an asterisk. 

Note: The FORMAT option applies only to a partitioned data set whose members 
have been created by the linkage editor (that is, the directory entries are at least 
34 bytes long). If a directory entry is less than 34 bytes, a message is issued and 
the entry is printed in unedited format; if the entry is longer than 34 bytes, it is 
assumed that it is created by the linkage editor. 

Figure 19-2 shows an edited entry for a partitioned member (mANUCOl). The 
entry is shown as it is listed by the IEHLIST program. 

OTHER INFORMATION INDEX 



SCATTER FORMAT SCTR = £ 


SCATTER/ 


rRANSL 


VTION TABLE TTR 


IN 


HEX, LEN OF SCRT LIST IN DEC, 


LEN OF TRANS TABLE IN DEC, 






ESDID OF 


FIRST 


TEXT RCD IN DEC 


, ESDID OF CSECT 


CONTAINING ENTRY POINT IN DEC 


OVERLAY FORMAT ONLY=NOTE LIST RCD TTR IN HEX, NUMBER 


OF ENTRIES IN 


NOTE 


LIST RCD IN DEC 


ALIAS 


NAMES 


ALIAS 


MEMBER 


MAMES WILL BE FOLLOWED 


BY 


AN ASTERISK 


IN THE 


PDS FORMAT LISTING 














ATTRIBUTE INDEX 








BIT 


ON 


OFF 


BIT 


ON 


OFF 


BIT 


ON 


OFF 


BIT 


ON OFF 





RENT 


NOT RENT 


4 


OL 


NOT OL 


8 


NOT DC 


DC 


12 


NOT EDIT EDIT 


1 


REUS 


NOT REUS 


5 


SCTR 


BLOCK 


9 


ZERO ORG 


NOT ZERO 13 


SYMS NO SYMS 


2 


ONLY 


NOT ONLY 


6 


EXEC 


NOT EXEC 


10 


EP ZERO 


NOT ZERO 14 


F LEVEL £ LEVEL 


3 


TEST 


NOT TEST 


7 


1 TXT 


MULTI RCD 


1 1 


NO RLD 


RLD 


15 


REFR NOT REFR 


MEMBER 


ENTRY 


ATTR 


REL 


ADDR-HEX CONTIG 




LEN 1ST ORB 1ST 


SSI 


VS AUTH OTHER 


NAME 


PT-HEX HEX 


BEGIN 


1ST 


TXT STOR-DEC 




TXT-DEC TXT-HEX 


INFO 


ATTR REQ INFORMATION 


IEANUC01 


000000 06E2 


000004 


00020F 000166248 


0927 




ABSENT 


880000 NO SCTR=000000, 






















00484,01084,32,32 



OF THE 00002 DIRECTORY BLOCKS ALLOCATED TO THIS PDS, 00001 ARE(IS) COMPLETELY UNUSED 

Figure 19-2. Edited Partitioned Directory Entry 
Unedited (Dump) Format 



The user may choose the unedited format. If this is the case, IEHLIST lists each 
member separately. 

Figure 19-3 shows how the information in Figure 19-1 is listed. 

Note: A listing organized as shown in Figure 19-3 can also be obtained by usinj 
IEBPTPCH (see "IEBPTPCH Program "). 



MEMB A TTR 

MEMB B TTR 

MEMB C TTR 

MEMB n TTR 



USER DATA 
USER DATA 
USER DATA 
USER DATA 



Figure 19-3. Sample Partitioned Directory Listing 



To correctly interpret user data information, the user must know the format of 
the partitioned entry. The formats of directory entries are discussed in 0S/VS1 
System Data Areas, SY28-0605, and OS/VS2 System Data Areas, SY28-0606. 



Listing a Volume Table of Contents 

IEHLIST can be used to list, partially or completely, entries in a specified volume 
table of contents (VTOC). The program lists the contents of selected data set 
control blocks (DSCBs) in edited or unedited form. 



Edited F : ormat 



| Note: VSAM data spaces are identified only; not the data sets within them. 



Two edited formats are available. One is a comprehensive listing of the DSCBs in 
the VTOC. It provides the status and attributes of the volume, and describes in 
depth the data sets residing on the volume. This listing includes: 

• Logical record length and block size 
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Initial and secondary allocations 

Upper and lower limits of extents 

Alternate track information 

Available space information, in detail 

Option codes (Not applicable with VSAM data spaces) 

Record formats 

A VTOC consists of as many as seven types of DSCBs which contain information 
about the data sets residing on the volume: 

Identifier DSCB — Format 1 

Index DSCB — Format 2 

Extension DSCB — Format 3 

VTOC DSCB — Format 4 

Free Space DSCB — Format 5 

Shared Extent DSCB — Format 6 

Free VTOC DSCB — Format 

The first DSCB in a VTOC (and on your listing) is always a VTOC (Format 4) 
DSCB. It defines the scope of the VTOC itself; that is, it contains information 
about the VTOC and the volume rather than the data sets referenced by the 
VTOC. 

The VTOC (Format 4) DSCB is followed, when necessary, by the Free Space 
(Format 5) DSCB, which describes the space available on the volume for 
allocation to other data sets. More than one Format 5 DSCB may be required to 
describe the available space on a volume because each Format 5 DSCB describes 
only 26 extents. 

The Format 4 and Format 5 DSCBs are followed, in any order, by Format 1, 2, 
3, or 6 DSCBs. 

Each Identifier (Format 1) DSCB contains information about a particular data set 
or data space residing on the volume. This type of DSCB describes the 
characteristics and up to three extents of the data set or data space. 

For data sets having indexed sequential organization, additional characteristics 
are specified in an Index (Format 2) DSCB pointed to by the Identifier (Format 
1) DSCB. 

Additional extents are described in an Extension (Format 3) DSCB pointed to by 
the Identifier (Format 1) DSCB or in the Index (Format 2) DSCB for an 
indexed sequential data set. 

A Shared Extent (Format 6) DSCB is used for shared-cylinder allocation. It 
describes the extent of space (one or more contiguous cylinders) that is being 
shared by two or more data sets. The Shared Extent (Format 6) DSCB is pointed 
to by the VTOC (Format 4) DSCB. Subsequent Format 6 DSCBs are pointed to by 
the previous Format 6 DSCB. 

A Free VTOC Record (Format 0) DSCB, which indicates space available for 
another DSCB, is not listed by IEHLIST. They are 140-byte records, consisting of 
binary zeros, that are overwritten with Format 1, 2, 3, and 6 DSCBs when a new 
data set is allocated, and with Format 5 DSCBs when space is released. 
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Figure 19-4 shows a sample listing of the edited format. This sample illustrates 
how each DSCB will appear on a listing, although in many cases the VTOC may 
not contain all possible types. The information is in columns, with the values or 
numbers appearing underneath each item's heading. 



SYSTEMS SUPPORT UTILITIES IEHLIST 


PAGE 1 


CONTENTS OF VTOC ON VOL EXAMPL 




# FORMAT 4 DSCB NO AVAIL/MAX DSCB /MAX DIRECT NO AVAIL NEXT ALT FORMAT 6 LAST FMT 1 VTOC EXTENT THIS DSCB # 
DSCBS PER TRK BLK PER TRK ALT TRK TRK(C-H) (C-H-R) DSCB( C-H-R )/LOW( C-H ) HIGH! C-H ) ( C-H-R ) 
15a 16 10 30 200 5 5 5 5 9 5 1 


FORMAT 5 DSCB A = NUMBER OF TRKS IN ADDITION TO FULL CYLS IN THE EXTENT 

TRK FULL TRK FULL TRK FULL TRK FULL TRK FULL 
£ ADDR CYLS A ADDR CYLS A ADDR CYLS A ADDR CYLS A ADDR CYLS 
17 3 3 110 189 


TRK FULL 
A ADDR CYLS A £ 


f DSCB( C-H-R) 5 2 






RECFM OPTCD BLKSIZE • 
F 100 


EXAMPLE. OF. COMBINED. FORMATS. ONE. AND. TWO 1 FXAMPL 1 36699 27469 1 IS 


• LRECL KEYLEN INITIAL ALLOC 2ND ALLOC/LAST BLK PTR( T-R-L ) USED PDS BYTES FMT 
100 4 ABSTR 


2 OR 3( C-H-R )/DSCB( C-H-R) • 
5 3 5 4 


• EXTENTS NO LOW( C-H ) HIGH! C-H ) 
6 10 9 




m 2MIND( M-B-C-H )/3MIND( M-B-C-H )/L2MFN( C-H-R )/L3MIN( C-H-R )/CYLAD( M-B-C-H )/ADLIN( M-B-C-H )/ADHIN( M-B-C-H l/NOBYT/ NOTRK 
00000000000000 10 10 90000 10 10 9 70 


m LTRADf C-H-R )/LCYAD( C-H-R )/LMSAD( C-H-R )/LPRAD( M-B-C-H-R ) /NOLFV /CYLOV/ TAGDT/ PRCTR / 
w 603 10 910001061 12 1 20 

UNABLE TO CALCULATE EMPTY SPACE. 


QVRCT/ RORG1/PTRDSI C-H-R ) A 

• 

RECFM OPTCD BLKSIZE 

V 3504 • 


EXAMPLE. OF. COMBINED. FORMATS. ONE. AND. THREE 1 EXAMPL 1 36699 27069 16 PS 


LRECL KEYLEN INITIAL ALLOC 2ND ALLOC/LAST BLK PTR( T-R-L) USED PDS BYTES FMT 
9 3500 TRKS 1 15 1 1723 


2 OR 3( C-H-R 1/DSCBI C-H-R ) 

5 6 5 5 9 


EXTENTS NO LOW( C-H ) HIGH(C-H) NO LOW( C-H ) HIGH( C-H ) NO LOW! C-H ) HIGH(C-H) 
m .001011020220303 * 
304044050550606 
607 07 7 08 08809 09 
A 910101 11 11111212 a 
w 12 1313131414 14 1515 w 
15 16 16 

ON THE ABOVE DATA SET, THERE ARE EMPTY TRACK! S ) . ^ 


THERE ARE 192 EMPTY CYLINDERS PLUS 3 EMPTY BRACKS ON THIS VOLUME 
• THERE ARE 154 BLANK DSCBS IN THE VTOC ON THIS VOLUME 





Figure lS>-4. Sample Printout of a Volume Table of Contents 



Unedited (Dump) Format 



The second edited format is an abbreviated description of the data sets. It is 
provided by default when no format is requested specifically. It provides the 
following information: 

Data set or data space name 

Creation date (dddyy) 

Expiration date (dddyy) 

Password indication 

Organization of the data set or data space 

Extent(s) 

Volume serial number 

The last line in the listing indicates how much space remains in the VTOC. 



This option produces a complete hexadecimal listing of the DSCBs in the VTOC. 
The listing is in an unedited dump form, requiring the user to know the various 
formats of applicable DSCBs. The VTOC overlay for IEHLIST listings of VTOCs in 
dump format (Order Number ZM08-0033) is useful in identifying the fields of 
the DSCBs. 
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Input and Output 



Control 



Refer to 0S/VS1 System Data Areas, SY28-0605, or 0S/VS2 System Data Areas, 
SY28-0606, for a discussion of the various formats that data set control blocks 
can assume. 



IEHLIST uses the following input: 

• One or more source data sets that contain the data to be listed. The input data 
set(s) can be a VTOC data set or a partitioned data set. 

• A control data set, which contains utility control statements that are used to 
control the functions of IEHLIST. 

IEHLIST produces as output a message data set, which contains the result of the 
IEHLIST operations. The message data set includes the listed data and any error 
messages. 

IEHLIST produces a return code to indicate the results of program execution. The 
return codes and their meanings are: 

• 00, which indicates successful completion. 

• 08, which indicates that an error condition caused a specified request to be 
ignored. Processing continues. 

• 12, which indicates that a permanent input/output error occurred. The job is 
terminated. 

• 16, which indicates that an unrecoverable error occurred while reading the 
data set. The job is terminated. 



IEHLIST is controlled by job control statements and utility control statements. 
The job control statements are used to execute or invoke IEHLIST and to define 
the data sets used and produced by IEHLIST. 

Utility control statements are used to control the functions of the program and to 
define those data sets or volumes to be modified. 



Job Control Statements 



Table 19-1 shows the job control statements necessary for using IEHLIST. 

Table 19-1. IEHLIST Job Control Statements 

Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (PGM=IEHLIST) or, if the job control statements 

reside in a procedure library, the procedure name. Additional PARM 
information can be specified to control the number of lines printed per 
page. See "PARM Information on the EXEC Statement" below. 

SYSPRINT DD Defines a sequential message data set. 

anynamel DD Defines a permanently mounted volume. 

anyname2 DD Defines a mountable device type. 

SYSIN DD Defines the control data set. The control data set normally follows the job 

control language in the input stream; however, it can be defined as an 
unblocked sequential data set or member of a procedure library. 

The "anynamel" DD statement can be entered: 

//anynamel DD UNIT=xxxx,VOLUME=SER=xxxxxx,DISP=OLD 
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Restrictions 



The unit and VOLUME parameters define the device type and volume serial 
number. The DlSP=OLD specification prevents the inadvertent deletion of the 
data set. This statement is arbitrarily assigned the ddname DD1 in the IEHLIST 
examples. 

When deferred mounting is required, the "anyname2" DD statement can be 
entered: 

//anyname2 DD UNIT=(xxxx„ DEFER), VOLUME=(PRIVATE,...),E>ISP=OLD 

See "Appendix C: DD Statements for Defining Mountable Devices" for 
information on defining mountable devices. This statement is arbitrarily assigned 
the ddname DD2 in the IEHLIST examples. Statements defining additional 
mountable devices are assigned ddnames DD3, DD4, etc. 

With the exception of the SYSIN and SYSPRINT DD statements, all DD statements 
in this table are used as device allocation statements, rather than as true data 
definition statements. 



The block size for the SYSPRINT data set must be a multiple of 121. The 
block size for the SYSIN data set must be a multiple of 80. Any blocking 
factor can be specified for these block sizes. 

An "anynamel" DD statement must be included for each permanently 
mounted volume referred to in the job step. (The system residence volume is 
considered to be a permanently mounted volume.) 

An "anyname2" DD statement must be included for each mountable device to 
be used in the job step. 

Because iehlist modifies the internal control blocks created by device 
allocation DD statements, IEHLIST job control statements must not include the 
DSNAME parameter. (All data sets are defined explicitly or implicitly by utility 
control statements.) 

When IEHLIST is dynamically invoked in a job step containing another 
program, the DD statements defining mountable devices for IEHLIST must be 
included in the job stream prior to DD statements defining data sets required 
by the other program. 

IEHLIST cannot support empty space calculations for data sets allocated in 
blocks when the block sizes are approximately the same as or larger than the 
track size. The empty block calculation gives only approximate indications of 
available space. When IEHLIST cannot supply an approximate number, the 
"Unable to Calculate" message is issued. 

IEHLIST specifications do not allow for protection of the object being listed. If 
another program updates a block of the data set just prior to IEHLIST reading 
the data set, a message (IEH105I or IEH108I) may be issued. In the case of 
LISTVTOC, the output produces by IEHLIST may be incorrect. When this 
happens, you should rerun the job. 
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PARM Information on the EXEC Statement 

Additional information can be specified in the PARM parameter of the EXEC 
statement to control the number of lines printed per page. The PARM parameter 
can be coded: 

PARM='LINECNT=xx' 

The LINECNT parameter specifies the number of lines, xx, to be printed per 
page; xx is a decimal number from 01 through 99. If LINECNT is not specified, 
58 lines are printed per page. The PARM field cannot contain embedded blanks, 
zeros, or any other PARM keywords, or the default of 58 is used. 

Utility Control Statements 

IEHLIST is controlled by the following utility control statements: 

• L1STPDS statement, which is used to request a directory listing of one or more 
partitioned data sets. 

• LISTVTOC statement, which is used to request a listing of all or part of a 
volume table of contents. 



LISTPDS Statement 



The listpds statement is used to request a directory listing of one or more 
partitioned data sets that reside on the same volume. 

The format of the LISTPDS statement is: 

[label] LISTPDS DSNAME=(name[,name]...) 

[,VOL=deWce=ser/'a/] 
{,DUMP} 
{,FORMAT} 

where: 

DSNAME= (name[,name] . . . ) 

specifies the fully qualified names of the partitioned data sets whose 
directories are to be listed. A maximum of ten names is allowed. If the list 
consists of a single name, the parentheses can be deleted. 

VOL=deWce=ser/a/ 

specifies the device type and volume serial number of the volume on which the 
partitioned data sets reside. If VOL is omitted, the data sets are assumed to 
reside on the system residence volume. 

DUMP 

specifies that the listing is to be in unedited, hexadecimal form. 

FORMAT 

specifies that the listing is to be edited for each directory entry. 

Before printing the directory entries on the first page, an index is printed 
explaining the attributes (fields 3 and 10) and other information (field 12). OTHER 
information INDEX explains scatter and overlay format data as it appears in 
the listing; ATTRIBUTE INDEX explains each attribute bit. 

Note: The LISTPDS statement may be used only on a partitioned data set whose 
members have been created by the linkage editor. Members that have not been 
created by the linkage editor cause their directory entries to be listed in unedited 
(DUMP) format. 
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LISTVTOC Statement 



IEHLIST Examples 



The LISTVTOC statement is used to request a partial or complete listing of the 
entries in a specified volume table of contents. 

The format of the LISTVTOC statement is: 

[label] LISTVTOC {DUMP} 

{FORMAT} 

[,DATE=cWdyy] 

[, VOL = device = serial] 

[,DSNAME= (name[,name]. . .) 

where: 

DUMP 

specifies that the listing is to be in unedited, hexadecimal form. If both DUMP 
and FORMAT are omitted, an abbreviated edited format is generated by 
default. 

FORMAT 

specifies that a comprehensive edited listing is to be generated. If both 
FORMAT and DUMP are omitted, an abbreviated edited format is generated by 
default. 

DATE=dcfdyy 

specifies that each entry that expires before this date is to be flagged with an 
asterisk (*) in the listing. This parameter applies only to the abbreviated edited 
format. The date is represented by ddd, the day of the year, and yy, the last 
two digits of the year. If DATE is omitted, no asterisks appear in the listing. 

VOL = device = serial 

specifies the device type and volume serial number of the volume whose table 
of contents is to be listed. If VOL is omitted, the system residence volume is 
assumed. 

DSNAME== (name[,name] ...) 

specifies the fully qualified names of the data sets whose entries are to be 
listed. A maximum of ten names is allowed. If DSNAME is omitted, the entire 
volume (able of contents is listed. 



The following examples illustrate some of the uses of IEHLIST. Table 19-2 can be 
used as a quick reference guide to IEHLIST examples. The numbers in the 
"Example" column point to examples that follow. 



Table 19-2. iehlist Example Directory 

Operation Device Comments 



Example 



LIST 



LIST 



2314 or 2319 
Disk, 1 3330 
Disk, system 
output device 

2314 Disk, 
system output 
device 



Three partitioned directories are to 
be listed on the system output device. 



Volume table of contents is to be 
listed in edited form; selected 
data set control blocks are listed 
in unedited form. 



1 Note that the 2319 disk is functionally equivalent to the 2314 disk; to use the 2319, specify 
2314 in the control statement. 
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IEHLIST Example 1 



IEHLIST Example 2 



Note: In the iehlist examples, the exec statement and the sysprint DD 
statement can be replaced with the following job control statement: 

// EXEC PROC=LIST 

The EXEC statement invokes the following IBM-supplied cataloged procedure: 

//LIST EXEC PGM=IEHLIST,REGION=44K 

//DDSRV DD VOLUME=REF=SYSl.SVCLIB,DISP=OLD 

//SYSPRINT DD SYSOUT=A 



In this example, a partitioned directory existing on the system residence volume 
is to be listed. In addition, two partitioned directories existing on a 2314 or 2319 
volume are to be listed. 



The example follows: 

//LISTPDIR JOB 09#550,BLUE 
// EXEC PGM=IEHLIST 

//SYSPRINT DD SYSOUT=A 



//DD1 DD 
//DD2 DD 
//SYSIN DD 
LISTPDS 
LISTPDS 
/* 



UNIT=3330,VOLUME=SER=1 11111 ,DISP=OLD 
UNIT=23 1 4 , VOLUME=SER=23 1 400 , DISP=OLD 
* 

DSNAME=PARSET1 

DSNAME=(PART1 , PART 2 ) , VOL=23 1 4=231 400 



The control statements are discussed below: 

• DDl DD defines the system residence device. 

• DD2 DD defines a mountable device on which a 2314 volume (231400) is to 
be mounted. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• The first LISTPDS statement indicates that the partitioned data set directory 
belonging to data set PARSETl is to be listed. This data set exists on the 
system residence volume. 

• The second LISTPDS statement indicates that partitioned directories belonging 
to data sets PARTI and PART2 are to be listed. These data sets exist on a 2314 
volume (231400). 



In this example, a volume table of contents in edited form, is to be listed. The 
edited listing is supplemented by an unedited listing of selected data set control 
blocks. 

The example follows: 

//LISTVTOC JOB 09#550,BLUE 

// EXEC PGM=IEHLIST 

//SYSPRINT DD SYSOUT=A 

//DD2 DD UNIT=2314,VOLUME=SER=231400,DISP=OLD 

//SYSIN DD * 

LISTVTOC FORMAT, VOL=2 3 14=2 3 1400 

LISTVTOC DUMP, VOL=23 14=231 400, DSNAME=( SET1 , SET2 , SET3 ) 
/* 

The control statements are discussed below: 

• DD2 DD defines a mountable device on which the volume containing the 
specified volume table of contents is to be mounted. 

• SYSIN DD defines the control data set which follows in the input stream. 



IEHLIST Program for VS2 Release 2 19-9 



The first LISTVTOC statement indicates that the volume table of contents on 
the specified 2314 volume is to be listed in edited form. 

The second LISTVTOC statement indicates that the data set control blocks 
representing data sets SET1, SET2, and SET3 are to be listed in unedited form. 
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IEHMOVE Program for VS1 Release 3 



IEHMOVE is a system utility used to move or copy logical collections of operating 
system data. (See "Introduction" for general system utility information.) 

IEHMOVE can be used to move or copy: 

• A data set residing on from one to five volumes. 

• A group of cataloged data sets. 

• A catalog, or portions of a catalog. 

• A volume of data sets. 

• Including or excluding data sets from a move or copy operation. 

The scope of a basic move or copy operation can be enlarged by: 

• Merging members from two or more partitioned data sets. 

• Including or excluding selected members. 

• Renaming moved or copied members. 

• Replacing selected members. 

If, for some reason, IEHMOVE is unable to successfully move or copy specified 
data, an attempt is made to reorganize the data and place it on the specified 
output device. The reorganized data — called an unloaded data set — is a sequential 
data set consisting of 80-byte blocked records that contain the source data and 
control information for subsequently reconstructing the source data as it 
originally existed. 

When an unloaded data set is moved or copied to a device that will support the 
data in its true form, the data is automatically reconstructed. For example, if the 
user attempts to move a partitioned data set to a tape volume, the data is 
unloaded to that volume. The user can re-create the data set simply by moving 
the unloaded data set to a direct access volume. 

A move operation differs from a copy operation in that a move operation 
scratches source data if the data set resides on a direct access source volume, 
while a copy operation leaves source data intact. In addition, for cataloged data 
sets, a move operation updates the catalog to refer to the moved version (unless 
otherwise specified), while a copy operation leaves the catalog unchanged. 

Space can be allocated for a data set on a receiving volume either by the user 
(through the use of DD statements in a prior job step) or by IEHMOVE in the 
IEHMOVE job step. If the source data is unmovable (that is, if it contains location 
dependent code), the user should allocate space on the receiving volume using 
absolute track allocation to ensure that the data set is placed in the same relative 
location on the receiving volume as it was on the source volume. Unmovable 
data can be moved if space is allocated by IEHMOVE, but the data will not be in 
the same location on the receiving volume as it was on the source volume. When 
data sets are to be moved between unlike devices, a secondary allocation should 
be made to ensure that ample space is available on the receiving volume. 

Space for a new data set cannot be allocated by the user under the following 
circumstances: 
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• When the organization of the data set to be moved or copied is direct and the 
data set is not to be unloaded, iehmove cannot determine whether the new 
data set is empty. 

• When a partitioned data set is being moved as part of a move volume 
operation and the data set is not to be unloaded. If the user does preallocate a 
partitioned data set in this case, no merging takes place. 

If IEHMOVE performs the space allocation for the new data set, the space 
requirement information of the old data set (if available) is used. This space 
requirement information is obtained from the DSCB of the source data set, if it is 
on a direct access device, or the control information in the case of an unloaded 
data set. 

If space requirement information is available, IEHMOVE uses this information to 
derive an allocation of space for the receiving volume, taking into account the 
differences in device characteristics, such as track capacity and overhead factors. 
However, when data sets with variable or undefined record formats are being 
moved or copied between unlike devices, no assumption can be made about the 
space that each individual record needs on the receiving device. 

In general, when variable or undefined record formats are to be moved or copied, 
IEHMOVE attempts to allocate sufficient space. This might cause too much space 
to be allocated under the following circumstances: 

• When moving or copying from a device with a relatively large block overhead 
to a device with a smaller block overhead, the blocks being small in relation to 
the block size. 

• When moving or copying from a device with a relatively small block overhead 
to a device with a larger block overhead, the blocks being large in relation to 
the block size. 

Note: Data sets with direct organization and variable or undefined record format 
always have the same amount of direct access space allocated by IEHMOVE. This 
practice preserves any relative track addressing system that might exist within the 
data sets. 

Note: When a data set has more than three extents and the space requirement 
for the remaining extents is more than eleven times the secondary allocation 
quantity, the data set should be allocated before performing the copy operation. 

A move or copy operation results in: (1) a moved or copied data set, (2) no 
action, or (3) an unloaded version of the source data set. These results depend 
upon the compatibility of the source and receiving volumes with respect to: 

• Size of the volumes. 

• Data set organization (sequential, partitioned, or direct access). 
Movability of the source data set. 



• Allocation of space on the receiving volume. 



Two volumes are compatible with respect to size if ( 1 ) the source record size 
does not exceed the receiving track size, or (2) the receiving volume supports the 
track overflow feature and the output is to be written with track overflow. (Refer 
to "Job Control Statements" for notes on the track overflow feature.) When 
using direct access organization, two volumes are compatible with respect to size 
if the source track capacity does not exceed the receiving track capacity. Direct 
access data sets moved or copied to a smaller device type or tape are unloaded. 
If the user wishes to load an unloaded direct access data set, it must be loaded to 
the same device type from which it was originally unloaded. 
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Table 20-1 shows the results of move and copy operations when the receiving 
volume is a direct access volume that is compatible in size with the source 
volume. The organization of the source data set is shown along with the 
characteristics of the receiving volume. 

Table 20-1. Move and Copy Operations — Direct Access Receiving Volume with Size 
Compatible with Source Volume 



Receiving Volume 
Characteristics 

Space allocated 
by IEHMOVE 
(movable data) 

Space allocated 
by IEHMOVE 
(immovable data) 

Space previously 
allocated, as yet 
unused 

Space previously 
allocated, partially 
used 



Sequential 
moved or copied 

moved or copied 

moved or copied 

no action 



Partitioned 



Direct Access 



moved or copied moved or copied 



moved or copied no action 



moved or copied no action 



moved or copied no action 

(merged) 



Table 20-2 shows the results of move and copy operations when the receiving 
volume is a direct access volume that is not compatible in size with the source 
volume. The organization of the source data set is shown along with the 
characteristics of the receiving volume. 

Table 20-2. Move and Copy Operations — Direct Access Receiving Volume with Size 
Incompatible with Source Volume 



Receiving Volume 
Characteristics 

Space allocated 
by IEHMOVE 

Space previously 
allocated, as yet 
unused 

Space previously 
allocated, partially 
used 



Sequential 
unloaded 

unloaded 
no action 



Partitioned 
unloaded 

unloaded 
no action 



Direct Access 
unloaded 

no action 
no action 



Table 20-3 shows the results of move and copy operations when the receiving 
volume is not a direct access volume. The organization of the source data set is 
shown along with the characteristics of the receiving volume. 

Table 20-3. Move and Copy Operations — Non-Direct Access Receiving Volume 



Receiving Volume 
Characteristics 

Movable data 

Unmovable data 



Sequential 
moved or copied 
unloaded 



Partitioned 

unloaded 

unloaded 



Direct Access 
unloaded 
no action 



Space cannot be previously allocated for a partitioned data set that is to be 
unloaded unless the SPACE parameter in the DD statement making the allocation 
implies sequential organization. Direct data sets cannot be previously allocated 
because they cannot be differentiated from partially used existing direct data sets. 

If a move or copy operation is unsuccessful, the source data remains intact. 

If a move or copy operation is unsuccessful and space was allocated by 
IEHMOVE, all data associated with that operation is scratched from the receiving 
direct access volume. If the receiving volume was tape, it will contain a partial 
data set. 
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If a move or copy operation is unsuccessful and space was previously allocated, 
no data is scratched from the receiving volume. If, for example, IEHMOVE moved 
104 members of a 105 -member partitioned data set and encountered an 
input/output error while moving the 105th member: 

• The entire partitioned data set is scratched from the receiving volume if space 
was allocated by IEHMOVE. 

• No data is scratched from the receiving volume if space was previously 
allocated. In this case, after determining the nature of the error, the user need 
move only the 105th member into the receiving partitioned data set. 

If a sequential data set is to be moved or copied and space attributes are not 
available either through a previous allocation or from the data set control block 
belonging to the source data set, IEHMOVE makes a default space allocation. The 
default allocation consists of a primary allocation of 72,500 bytes of storage 
(data and gaps) and up to 14 secondary allocations of 36,250 bytes each. 

When moving or copying a data set group or a volume containing 
password-protected data sets, the user must provide the password each time a 
data set is opened or scratched. 

IEHMOVE always moves or copies any user labels associated with an input data 
set. IEHMOVE does not take exits to a user's label processing routines. 

Note: If a data set that has only user trailer labels is to be moved from a tape 
volume to a direct access volume, space must be previously allocated on the 
direct access volume to ensure that a track is reserved to receive the user labels. 



Reblocking 



Data sets with fixed or variable records can be reblocked to a different block size 
by previously allocating the desired block size on the receiving volume. No 
reblocking can be performed when loading or unloading. 

When moving or copying data sets with undefined record format and reblocking 
to a smaller block size (that is, transferring records to a device with a track 
capacity smaller than the track capacity of the original device), the user must 
make the block size for the receiving volume equal to or larger than the size of 
the largest record in the data set being moved or copied. 

Moving or Copying a Data Set 

IEHMOVE can be used to move or copy sequential, partitioned, and direct access 
data sets, as follows: 

• A sequential data set can be: (1) moved from one direct access or non-direct 
access volume to another (or to the same volume provided that it is a direct 
access volume), or (2) copied from one direct access or non-direct access 
volume to another (or to the same volume provided that the data set name is 
changed and the receiving volume is a direct access volume). 

• A partitioned data set can be: (1) moved from one direct access volume to 
another (or to the same volume) or, (2) copied from one direct access volume 
to another (or to the same volume provided that the data set name is 
changed). 

• A direct access data set can be moved or copied from one direct access 
volume to another provided that the receiving device type is the same device 
type or a larger device type and that the record size does not exceed 32K. 

In addition, IEHMOVE can be used to move or copy multivolume data sets. To 
move or copy a multivolume data set, specify the complete volume list in the 
VOL=SER parameter on the DD statement. To move or copy a data set that 
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resides on more than one tape volume, specify the volume serial numbers of all 
the tape volumes and the sequence numbers of the data set on the tape volumes 
in a utility control statement. (You can specify the sequence number even if the 
data set to be moved or copied is the only data set on a volume.) To move or 
copy a data set to more than one tape volume, specify the volume serial numbers 
of all the receiving volumes in a utility control statement. 

A data set with the unmovable attribute can be moved or copied from one direct 
access volume to another or to the same volume provided that space has been 
previously allocated on the receiving volume. Change the name of a data set to 
move or copy it to the same volume. SVCLIB can be moved or copied to another 
location on the system residence volume, provided that space is available and 
that space has been previously allocated on that volume. IEHPROGM must be 
used immediately after such a move operation to rename the moved version 
sysi. svclib. After such a copy operation, iehprogm must be used to scratch 
the old version and to rename the copied version. In either case, IEHIOSUP must 
be used immediately after the IEHPROGM step to update the new version of 
SVCLIB. 

When moving or copying a BDAM data set from one device to another device of 
the same type, relative track and relative block integrity are maintained. 

When moving or copying a BDAM data set to a larger device, relative track 
integrity is maintained for data sets with variable or undefined record formats; 
relative block integrity is maintained for data sets with fixed record formats. 

When moving or copying a BDAM data set to a smaller device or a tape, the data 
set is unloaded. An unloaded data set is loaded only when it is moved or copied 
to the same device type from which it was unloaded. 

Table 20-4 shows basic and optional move and copy operations for sequential 
and partitioned data sets. 

Table 20-4. Moving and Copying Sequential and Partitioned Data Sets 



Operation Basic Actions 



Move 
Sequential 



Move 
Partitioned 



Move the data set. For direct access, 
scratch the source data. For cataloged 
data sets, update the catalog 
to refer to the moved data set. 

Move the data set. For direct access, 
scratch the source data. For cataloged 
data sets, update the catalog to refer 
to the moved data set. 



Copy 
Seqeuntial 

Copy 
Partitioned 



Copy the data set. The source data set 
is not scratched. The catalog is not 
updated to refer to the copied data set. 

Copy the data set. The source data is 
not scratched. The catalog is not 
updated to refer to the copied data 
set. 



Optional Actions 

Prevent automatic cataloging of the 
moved data set. Rename the moved 
data set. 



Prevent automatic cataloging of the 
moved data set. Rename the moved 
data set. Re-allocate directory space. 
(Not possible if the space was not 
allocated by iehmove during this 
move function.) Perform a merge 
operation using members from two or 
more data sets. Move only selected 
members. Replace members. Unload 
the data set. 

Uncatalog the source data set. Catalog 
the copied data set on the receiving 
volume. Rename the copied data set. 

Uncatalog the source data set. Catalog 
the copied data set on the receiving 
volume. Rename the copied data set. 
Re-allocate directory space. (Not 
possible if the space previously 
allocated is partially used.) Perform a 
merge operation using members from 
two or more data sets. Copy only 
selected members. Replace members. 
Unload the data set. 
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IEHMOVE moves or copies partitioned members in the order in which they appear 
in the partitioned directory. That is, moved or copied members are placed in 
collating sequence on the receiving volume. 

Figure 20-1 shows a copied partitioned data set. Note that the members are 
copied in the order in which they appear in the partitioned directory. IEBCOPY 
can be used to copy data sets whose members are not to be collated. 



Source data set 



Copied data set 




Figure 20-1. Partitioned Data Set Before and After an iehmove Copy Operation 

Members that are merged into an existing data set are placed, in collating 
sequence, after the last member in the existing data set. 

Figure 20-2 shows members from one data set merged into an existing data set. 
Note that members A, C, and G from the existing data set are copied to the 
receiving volume before members B and F are copied from the source data set. 
Members B and F are copied in collating sequence. 



Source data set 



Existing data set 
prior to merge 




Existing data set 
after merge 




Figure 20-2. Merging Two Data Sets Using iehmove 

Figure 20-3 shows how members from two data sets are merged into an existing 
data set. Members from additional data sets can be merged in a like manner. 
Note that members A, C, and G are copied from the existing data set before any 
members are copied from the source data sets. Members F, B, D, and E from the 
source data sets are copied in collating sequence. 
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Source data sets 



Existing data set 
prior to merge 




Existing data set 
after merge 




New members 
are placed in 
collating sequence 
after existing 
members 



Figure 20-3. Merging Three Data Sets Using iehmove 

Moving or Copying a Group of Cataloged Data Sets 

IEHMOVE can be used to move or copy a group of data sets that are cataloged 
on the same volume and whose names are qualified by one or more identical 
names. For example, a group of data sets qualified by the name A.B can include 
data sets named A.B.D and A.B.E, but could not include data sets named A.C.D or 
A.D.F. 

Additional data sets not belonging to the specified data set group can be included 
in the move or copy operation; data sets belonging to the group can be excluded. 

If a group of data sets is moved or copied to magnetic tape, the data sets must 
be retrieved one by one by data set name and file-sequence number, or by 
file-sequence number for unlabeled or non-standard labeled tapes. 

IEHLIST can be used to determine the structure of the catalog. 

Table 20-5 shows basic and optional move and copy operations for a group of 
cataloged data sets. 



Table 20-5. 

Operation 

Move group 
of cataloged 
data sets 



Copy group 
of cataloged 
data sets 



Moving and Copying a Group of Cataloged Data Sets 



Basic Actions 

Move the data set group (excluding 
password-protected data sets) to the 
specified volumes. Scratch the source 
data sets (direct access only). 
Merging is not done. 



Copy the data set group (excluding 
password-protected data sets). Source 
data sets are not scratched. 
Merging is not done. 



Optional Actions 

Prevent updating of the catalog. 
Include password-protected data 
sets in the operation. Include 
additional data sets in the 
operation. Exclude data sets 
from the operation. Unload 
data sets. 

Include password-protected data 
sets in the operation. Uncatalog 
the source data sets. Catalog 
the copied data sets on the 
receiving volumes. Include 
additional data sets in the 
operation. Unload a data set or 
sets. Exclude data sets from 
the operation. 
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Moving or Copying a Catalog 

IEHMOVE can be used to move or copy a catalog or portions of a catalog without 
copying the data sets represented by the cataloged entries. The SYSCTLG (system 
catalog) data set need not be defined on the receiving volume before the 
operation. If, however, SYSCTLG was defined before the operation, the data set 
organization must not have been specified in the DCB field. Moved or copied 
entries are merged with any existing entries on the receiving volume. Note that 
the receiving volume must be a direct access volume unless the catalog is to be 
unloaded. 

Table 20-6 shows basic and optional move and copy operations for the catalog. 



Table 20-6. Moving and Copying the Catalog 
Operation Basic Actions 

Move catalog Move entries from the catalog to the 
specified direct access volume. 
Scratch the last index of all 
entries in the source catalog. 

Copy catalog Copy entries from the catalog to the 
specified direct access device. The 
source catalog is not scratched. 



Optional Actions 

Exclude selected entries from 
operation. Move an unloaded 
version of the catalog. Unload 
the catalog to the magnetic 
tape volume. 

Exclude selected entries from 
the operation. Copy an unloaded 
version of the catalog. Unload 
the catalog to a tape volume. 



Moving or Copying a Volume of Data Sets 

IEHMOVE can be used to move or copy the data sets of an entire direct access 
volume to another volume or volumes. A move operation differs from a copy 
operation in that the move operation scratches source data sets, while the copy 
operation does not. For both operations, any cataloged entries associated with 
the source data sets remain unchanged. IEHPROGM can be used to uncatalog all 
of the cataloged data sets and recatalog them according to their new location. 

If the source volume contains a SYSCTLG data set, that data set is the last to be 
moved or copied onto the receiving volume. 

If a volume of data sets is moved or copied to tape, the data sets must be 
retrieved one by one by data set name and file-sequence number, or by 
file-sequence number for unlabeled or non-standard labeled tapes. 

When copying a volume of data sets, the user has the option of cataloging all 
source data sets in a SYSCTLG data set on a receiving volume. However, if a 
SYSCTLG data set exists on the source volume, error messages indicating that an 
inconsistent index structure exists are generated when the source SYSCTLG 
entries are merged into the SYSCTLG data set on the receiving volume. 

The move-volume feature does not merge partitioned data sets. If a data set on 
the volume to be moved or copied has a name identical to a data set name on 
the receiving volume, the data set is not moved, copied, or merged onto the 
receiving volume. 

Table 20-7 shows basic and optional move and copy operations for a volume of 
data sets. 
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Table 20-7. Moving and Copying a Volume of Data Sets 



Operation 

Move a volume 
of data sets 



Copy a volume 
of data sets 



Basic Actions 

Move all data sets not protected by a 
password to the specified direct access 
volumes. Scratch the source data sets 
for direct access volumes. The catalog 
is not updated. 

Copy all data sets not protected by a 
password to the specified direct access 
volume. The source data sets are not 
scratched. 



Optional Actions 

Include password-protected data 
sets in the operation. Move to a 
tape volume. 



Include password-protected data 
sets in the operation. Catalog all 
copied data sets on the receiving 
volume (direct access only). 
Copy to a tape volume. 



Moving or Copying Direct Data Sets with Variable Spanned Records 

IEHMOVE can be used to move or copy direct data sets with variable spanned 
records from one direct access volume to a compatible direct access volume, 
provided that the record size does not exceed 32K. 

Because a direct access data set can reside on one to five volumes (all of which 
must be mounted during any move or copy operation), it is possible for the data 
set to span volumes. However, single variable spanned records are contained on 
one volume. 

Relative track integrity is preserved in a move or copy operation for spanned 
records. Moved or copied direct access data sets occupy the same relative 
number of tracks that they occupied on the source device. 

If a direct data set is unloaded (moved or copied to a smaller device or tape), it 
must be loaded back to the same device type from which it was originally 
unloaded. 

When moving or copying variable spanned records to a larger device, record 
segments are combined and re-spanned if necessary. Because the remaining track 
space is available for new records, variable spanned records are unloaded before 
being moved or copied back to a smaller device. 

If a user wishes to create a direct data set without using data management BDAM 
macros, all data management specifications must be followed. Special attention 
must be given to data management specifications for R0 track capacity record 
content, segment descriptor words, and the BFTEK=R parameter. 

When moving or copying a multivolume data set, the secondary allocation for 
direct data sets should be at least two tracks. (See the "WRITE SZ" macro in 
OS/VS Data Management Macro Instructions, GC26-3793.) 



Input and Output 



IEHMOVE uses the following input: 

• One or more data sets, which contain the data to be moved, copied, or merged 
into an output data set. 

• A control data set, which contains utility control statements that are used to 
control the functions of the program. 

• A work data set, which is a work area used by IEHMOVE. 
IEHMOVE produces the following output: 

• An output data set, which is the result of the move, copy, or merge operation. 

• A message data set, which contains informational messages (for example, the 
names of moved or copied data sets) and error messages, if applicable. 
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IEHMOVE produces a return code to indicate the results of program execution. 
The return codes and their meanings are: 

• 00, which indicates successful completion. 

• 04, which indicates that a specified function was not completely successful. 
Processing continues. 

• 08, which indicates a condition from which recovery is possible. Processing 
continues. 

• 12, which indicates an unrecoverable error. The job step is terminated. 

• 16, which indicates that is it impossible to OPEN the SYSIN or SYSPRINT data 

set. 

Control 

IEHMOVE is controlled by job control statements and utility control statements. 
The job control statements are used to execute or invoke the program, define the 
devices and volumes used and produced by IEHMOVE, and prevent data sets from 
being deleted inadvertently. 

Utility control statements are used to control the functions of the program and to 
define those data sets or volumes that are to be used. 

Job Control Statements 

Table 20-8 shows the job control statements necessary for using IEHMOVE. 

Table 20-8. iehmove Job Control Statements 

Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (PGM=IEHMOVE) or, if the job control 

statements reside in a procedure library, the procedure name. This statement 
can include optional PARM information; see "PARM Information on the EXEC 
Statement" below. 

SYSPRINT DD Defines a sequential message data set. The data set can be written onto a 
system output device, a magnetic tape volume, or a direct access volume. 

SYSUT1 DD Defines a volume on which 3 work data sets required by IEHMOVE are 
placed. 

anynamel DD Defines a permanently mounted volume. (The system residence volume is 
considered to be a permanently mounted volume.) 

anyname2 DD Defines a mountable device type. 

tape DD Defines a tape volume to be used when moving or copying from or to a 

7-track tape volume, a 9-track tape volume not having standard labels, or a 
1600 bits per inch, 9-track tape volume on a single density unit, or when 
copying to an 800 bits per inch tape on a dual density unit. 

SYSIN DD Defines the control data set. The data set, which contains utility control 

statements, usually follows the job control statements in the input stream; 
however, it can be defined either as an unblocked sequential data set or as a 
member of a procedure library. 

The SYSUT1 DD statement can be coded: 

//SYSUTl DD UNIT=xxxx,VOLUME=SER=xxxxxx,DISP=OLD 

At least 3 utility work areas of 13, 13, and 26 contiguous tracks, respectively, 
must be available for work space on the volume defined by the SYSUTl DD 
statement. (This figure is based on a 2314 being the work volume. If a direct 
access device other than a 2314 is used, an equivalent amount of space must be 
available.) 
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The anynamel DD statement can be coded: 

//anynamel DD UNIT=xxxx,.VOLUME=SER=xxxxxx,DISP=OLD 

In the anynamel DD statement, the UNIT and volume parameters define the 
device type and volume serial number. The DISP=OLD specification prevents the 
inadvertent deletion of a data set. The anynamel DD statement is arbitrarily 
assigned the ddname DD1 in the IEHMOVE examples. 

The anyname2 DD statement can be coded: 

//anyname2 DD UNIT=xxxx,VOLUME=SER=xxxxxx,DISP=OLD 

When the number of volumes to be processed is greater than the number of 
devices defined by DD statements, there must be an indication (in the applicable 
DD statements) that multiple volumes are to be processed. This indication can be 
in the form of deferred mounting, as follows: 

//anyname2 DD UNIT=(xxxx„DEFER),VOLUME=(PRIVATE,...), 
// DISP=(...,KEEP) 

See "Appendix C: DD Statements for Defining Mountable Devices" for 
information on defining mountable devices. The anyname2 DD statement is 
arbitrarily assigned the ddname DD2 in the IEHMOVE examples. DD statements 
defining additional mountable device types are assigned names DD3, DD4, etc. 

The tape DD statement can be coded: 

//tape DD DSNAME=xxxxxxxx,UNIT=xxxx,VOLUME=SER=xxxxxx, 
// DISP=(...,KEEP),LABEL=( ),DCB=(TRTCH=C,DEN=x) 

when 7 -track tape is to be used. A utility control statement parameter refers to 
the tape DD statement for label and mode information. 

The date on which a data set is moved or copied to a magnetic tape volume is 
automatically recorded in the HDRl record of a standard tape label if a TODD 
parameter is specified in a utility control statement. An expiration date can be 
specified by including the expdt or RETPD subparameters of the LABEL 
keyword in the DD statement referred to by a TODD parameter. 

To define a sequence number for a data set on a tape volume, or to specify a 
specific device (for example, unit address 190), you must use a utility control 
statement instead of a DD statement. To move or copy a data set from or to a 
tape volume containing more than one data set, specify the sequence number of 
the data set in a utility control statement. To move or copy a data set from or to 
a specific device, specify the unit address (rather than a group name or device 
type) in a utility control statement. To copy to a unit record or unlabeled tape 
volume, specify any standard name or number in a utility control statement. 

IEHMOVE automatically calculates and allocates the amount of space needed for 
the work areas. No space parameter, therefore, should be coded in the SYSUTi 
DD statement. If, in the EXEC statement, POWER=3 is specified, the work space 
requirement is three times the basic requirements, etc. 

With the exception of the SYSIN and SYSPRINT DD statements, all DD statements 
shown in Table 20-8 are used as device allocation statements, rather than as true 
data definition statements. Because IEHMOVE modifies the internal control blocks 
created by device allocation DD statements, these statements must not include 
the dsname parameter. (All data sets are defined explicitly or implicitly by 
utility control statements.) 

A merge operation requires that one DD statement defining a mountable device 
be present for each source volume containing data to be included in the merge 
operation. 
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Restrictions 



Prior space allocations can be made by specifying a dummy execution of 
IEHPROGM before the execution of IEHMOVE. 

Blocked format data sets that do not contain user data TTRNs or keys can be 
reblocked or unblocked by including the proper keyword subparameters in the 
DCB operand of the DD statement used to previously allocate space for the data 
set. The new blocking factor must be a multiple of the logical record length 
originally assigned to the data set. (For a discussion of user data TTRNs, refer to 
OS/VS Data Management Services Guide, GC26-3783.) 



The block size for the SYSPRINT data set must be a multiple of 121. The 
block size for the SYSIN data set must be a multiple of 80. Any blocking 
factor can be specified for these block sizes. 

One anynamel DD statement must be included for each permanently mounted 
volume referred to in the job step. 

One anyname2 DD statement must be included for each mountable device to 
be used in the job step. 

When IEHMOVE is dynamically invoked in a job step containing another 
program, the DD statements defining mountable devices for IEHMOVE must be 
included in the job stream prior to DD statements defining data sets required 
by the other program. 



PARM Information on the EXEC Statement 



The EXEC statement for IEHMOVE can contain PARM information that is used by 
the program to allocate additional work space and/or control line density on 
output listings. The EXEC statement can be coded, as follows: 

// EXEC PGM=IEHMOVE[,PARM= {'POWER=n'} 

{'POWER=n,LINECNT=xx'} 
{'LINECNT=xx'}] 

The POWER=n parameter is used to request that the normal amount of space 
allocated for work areas be increased n times. The POWER parameter is used 
when 750 or more members are being moved or copied. The progression for the 
value of n is: 

• POWER=2 when 750 to 1,500 members are to be moved or copied. 

• POWER=3 when 1,501 to 2,250 members are to be moved or copied. 

• POWER=4 when 2,251 to 3,000 members are to be moved or copied. 

If POWER=2, the work space requirement on the SYSUTl volume is two times the 
basic requirement; if POWER=3, work space requirement is three times the basic 
requirement, etc. For example, if POWER=2, three areas of 26, 26, and 52 
contiguous tracks on a 2314 must be available. 

When moving or copying a catalog, the value of the POWER parameter can be 
calculated, as follows: 

n=(10D + V + 20G)/4000 

where D is the total number of data sets, aliases, and generation data set entries 
(which is the number of data set names printed by I EH LIST when LISTCTLG is 
specified); V is the total number of volumes used by these data sets (which is the 
number of lines printed by IEHLIST when LISTCTLG is specified); and G is the 
number of generation data sets. Approximate values can be used: 

• POWERS when 350 to 700 data sets are cataloged. 
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• POWER=3 when 701 to 1050 data sets are cataloged. 

• POWER=4 when 1051 to 1400 data sets are cataloged. 

The LlNECNT=xx parameter specifies the number of lines per page in the listing 
of the SYSPRINT data set; xx is a two-digit number. 

Job Control Language for the Track Overflow Feature 

A data set containing track overflow records can be moved or copied if the 
source volume and the receiving volume are mounted on direct access devices 
that support the track overflow feature. (For BDAM data sets, the source and 
receiving devices must be the same device type.) 

A data set that was written without track overflow can be moved or copied with 
or without track overflow or vice versa if the following conditions arc met: 

• Space was allocated for the data set prior to the request for a move or copy 
operation. 

• The DD statement used for that allocation included the subparameter to 
specify the changed track overflow value and all other desired values. (The 
RECFM specifications assigned when the data set was originally created are 
overridden by the RECFM subparameter in this DD statement.) 

If space has not been allocated, or if RECFM was not specified when space was 
allocated, the data set is moved or copied in accordance with RECFM 
specifications that were made when the data set was originally created. 

The track overflow attribute is not retained for a sequential data set that is 
moved or copied to a device other than a direct access device. 

Utility Control Statements 

IEHMOVE is controlled by the following utility control statements: 

MOVE DSNAME statement, which is used to move a data set. 

COPY DSNAME statement, which is used to copy a data set. 

MOVE DSGROUP statement, which is used to move a group of cataloged data 
sets. 

COPY DSGROUP statement, which is used to copy a group of cataloged data 
sets. 

MOVE PDS statement, which is used to move a partitioned data set. 

COPY PDS statement, which is used to copy a partitioned data set. 

MOVE catalog, which is used to move cataloged entries. 

COPY CATALOG statement, which is used to copy cataloged entries. 

MOVE VOLUME statement, which is used to move a volume of data sets. 

COPY VOLUME statement, which is used to copy a volume of data sets. 

In addition, there are four subordinate control statements that can be used to 
modify the effect of a MOVE DSGROUP, COPY DSGROUP, MOVE PDS, COPY PDS, 
MOVE CATALOG, or COPY CATALOG operation. The subordinate control 
statements are: 

• INCLUDE statement, which is used to enlarge the scope of a MOVE DSGROUP, 
copy DSGROUP, MOVE PDS, or COPY PDS statement by including a member 
or data set not explicitly included by the statement it modifies. 
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• exclude statement, which is used with a move dsgroup, copy dsgroup, 

MOVE PDS, COPY PDS, MOVE CATALOG, or COPY CATALOG Statement to 
exclude data from the move or copy operation. 

• REPLACE statement, which is used with a MOVE PDS or COPY PDS statement 
to exclude a member from a move or copy operation and to replace it with a 
member from another partitioned data set. 

• SELECT statement, which is used with MOVE PDS or COPY PDS statements to 
select members to be moved or copied and, optionally, to rename the specified 
members. 

Notes: FROM and CVOL should never appear in the same IEHMOVE utility control 
statement. FROMDD must be specified in the control statement when no data set 
label information is available. TODD must be specified in the control statement 
when an expiration data (EXPDT) or retention period (RETPD) is to be created or 
changed. 

MOVE DSNAME Statement 

The MOVE DSNAME statement is used to move a data set. The source data set is 
scratched. 

The format of the MOVE DSNAME statement is: 

[label] MOVE DSNAME=name 
,TO=dev/ce=//st 

[{,FROM=dewce=/»st} 

{,CVOL=dev/ce=ser/a/}] 

[,UNCATLG] 

[,RENAME=name] 

[,FROMDD=ddname] 

[,TODD=ddname] 

where: 

DSNAME==name 

specifies the fully qualified name of the data set to be moved. 

TO =dewce=//st 

specifies the volume or volumes to which the data set is to be moved. 

FROM=deWce=/»st 

specifies the volume or volumes on which the data set currently resides, if it is 
not cataloged. If the data set is cataloged and FROM is specified, the catalog is 
not updated. 

CVOL = device = serial 

specifies the device type and volume serial number of the volume on which the 
catalog search for the data set is to begin. If neither CVOL nor FROM is 
written, the data set is assumed to be cataloged on the system residence 
volume. 

UNCATLG 

specifies that the catalog entry pertaining to the data set is to be removed. 
This parameter should be used only if the source data set is cataloged. 
UNCATLG is ignored if the volume is identified by FROM. 

RENAME=name 

specifies that the data set is to be renamed, and indicates the new name. 
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COPY DSNAME Statement 



FROMDD=ddname 

specifies the name of a DD statement from which DCB and LABEL information 
are obtained. This parameter is valid for data sets residing on magnetic tape 
volumes. 

TODD=ddname 

specifies the name of a DD statement from which DCB and LABEL information 
are obtained. This parameter, which is valid for data sets to be moved to tape 
volumes, describes the mode and label of the volume where the moved data 
set is to reside. RECFM, LRECL, and BLKSIZE information is ignored. 

If the data set is cataloged, the catalog is automatically updated unless UNCATLG 
is specified. 

The FROMDD and TODD parameters can be omitted for 800 bits per inch, 9-track 
tape with standard labels on single density units or for 1600 bits per inch, 
9-track tape with standard labels on dual density units. 



The COPY DSNAME statement is used to copy a data set. 

The format of the COPY DSNAME statement is: 

[label] COPY DSNAME=name 
,TO=dewce=//st 
[{,FROM=dev/ce=/»'st} 
{,CVOL=dew'ce=sena/}] 

[,UNCATLG] 
[,CATLG] 

[,RENAME=name] 

[,FROMDD=ddname] 

[,TODD=ddname] 

where: 

DSNAME = name 

specifies the fully qualified name of the data set to be copied. 

TO=dewce=//'st 

specifies the volume or volumes on which the data set is to be copied. 

FROM=dev/"ce=//'st 

specifies the volume or volumes on which the data set currently resides, if it is 
not cataloged. 

C VOL =device = serial 

specifies the device type and volume serial number of the volume on which the 
catalog search for the data set is to begin. If neither CVOL nor FROM is 
written, the data set is assumed to be cataloged on the system residence 
volume. 

UNCATLG 

specifies that the catalog entry pertaining to the source data set is to be 
removed. This parameter should be used only if the source data set is 
cataloged. UNCATLG is ignored if the volume is identified by FROM. 

CATLG 

specifies that the copied data set is to be cataloged on its receiving volume if 
it is a direct access volume. If a catalog does not exist on the receiving 
volume, a new catalog is created. 
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RENAME == name 

specifies that the data set is to be renamed, and indicates the new name. 

FROMDD=ddname 

specifies the name of the DD statement from which DCB and LABEL 
information are obtained. DCB attributes for unloaded data sets are always 
RECFM=FB, LRECL=80, and blksize=800. This parameter is valid for data sets 
residing on tape volumes. 

TODD=ddname 

specifies the name of a DD statement from which DCB and LABEL information 
are obtained. This parameter, which is valid for data sets to be copies to 
magnetic tape volumes, describes the mode and label of the magnetic tape 
where the copied data set is to reside. RECFM, LRECL, and BLKSIZE 
information is ignored. 

Note: The source data set, if cataloged, remains cataloged unless UNCATLG is 
specified. 

The FROMDD and TODD parameters can be omitted for 800 bits per inch, 9-track 
tape with standard labels on single density units or for 1600 bits per inch, 
9-track tape with standard labels on dual density units. 



MOVE DSGROUP Statement 



The MOVE DSGROUP statement is used to move groups of data sets that are 
cataloged on the same volume and whose names are partially qualified by one or 
more identical names. Source data sets are scratched. Data set groups to be 
moved must reside on direct access volumes. 

INCLUDE and EXCLUDE statements, discussed later in this chapter, can be used 
to add to or delete data sets from the group. 

The format of the MOVE DSGROUP statement is: 

[label] MOVE DSGROUP[= name] 
,TO=dev/ce=//st 
[,CVOL=deWce=ser;a/] 
[,PASSWORD] 
[,UNCATLG] 
[,TODD =ddname] 

where: 

DSGROUP[ =name] 

specifies the cataloged data sets to be moved. If name, which is a qualified 
name, is not coded, all data sets cataloged on the specified volume are to be 
moved. If name is coded, all cataloged data sets whose names are qualified by 
this name are moved. If the name is a fully qualified data set name, only that 
data set is moved. 

TO=dew'ce=//'st 

specifies the volume or volumes to which the specified group of data sets is to 
be moved. 

C VOL = device = serial 

specifies the device type and volume serial number of the volume on which the 
catalog search for the data sets is to begin. If CVOL is omitted, the specified 
group of data sets is assumed to be cataloged on the system residence volume. 
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PASSWORD 

specifies that password protected data sets contained in the group are to be 
moved. If PASSWORD is omitted, only data sets that are not protected are 
moved. 

UNCATLG 

specifies that the catalog entries pertaining to the specified group of data sets 
are to be removed. 

TODD=ddname 

specifies the name of a DD statement from which DCB and LABEL information 
are obtained. This parameter, which is valid for data set groups to be moved 
to magnetic tape volumes, describes the mode and label of the magnetic tape 
where the moved data sets are to reside. RECFM, LRECL, and BLKSIZE 
information is ignored. TODD can be omitted for 800 bits per inch, 9-track 
tape with standard labels on single density units or for 1600 bits per inch, 
9-track tape with standard labels on dual density units. 

move dsgroup operations cause the specified catalog to be updated 
automatically unless UNCATLG is specified. 



COPY DSGROUP Statement 



The COPY DSGROUP statement is used to copy groups of data sets that are 
cataloged on the same control volume and whose names are partially qualified by 
one or more identical names. Data set groups to be copied must reside on direct 
access volumes. 

INCLUDE and EXCLUDE statements, discussed later in this chapter, can be used 
to add data sets to or delete data sets from the data set group to be copied. 

The format of the COPY DSGROUP statement is: 

[label] COPY DSGROUP[=name] 

,TO=dev/ce=//st 

[,C VOL = device = serial] 

[,PASSWORD] 

[,UNCATLG] 

[,CATLG] 

[,TODD=ddname] 

where: 

DSGROUP[= name] 

specifies the cataloged data sets to be copied. If name, which is a qualified 
name, is not coded, all cataloged data sets on the specified volume are to be 
copied. If name is coded, all cataloged data sets whose names are qualified by 
this name are copied. If the name is a fully qualified data set name, only that 
data set is copied. 

TO=deWce=//sf 

specifies the volume or volumes on which the specified group of data sets is to 
be copied. 

C VOL = device = serial 

specifies the device type and volume serial number of the volume on which the 
search for the catalog is to begin. If CVOL is omitted, the specified group of 
data sets is assumed to be cataloged on the system residence volume. 
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MOVE IPDS Statement 



PASSWORD 

specifies that password-protected data sets contained in the group are to be 
copied. If PASSWORD is omitted, only data sets that are not protected are 
copied. 

UNCATLG 

specifies that the catalog entries pertaining to the source group of data sets are 
to be removed. 

CATLG 

specifies that the copied data sets are to be cataloged on their receiving 
volumes if they are direct access volumes. If catalogs do not exist on the 
receiving volumes, they are created. 

TODD =ddname 

specifies the name of a DD statement from which DCB and LABEL information 
are obtained. This parameter, which is valid for data set groups to be copied 
to magnetic tape volumes, describes the mode and label of the magnetic tape 
on which the copied data sets are to reside. RECFM, LRECL, and BLKSIZE 
information is ignored. TODD can be omitted for 800 bits per inch, 9-track 
tapes with standard labels on single density units or for 1600 bits per inch, 
9-track tape with standard labels on dual density units. 

Note: The source data sets remain cataloged unless UNCATLG is specified. 



The MOVE PDS statement is used to move partitiohed data sets. When used in 
conjunction with INCLUDE, EXCLUDE, REPLACE, or SELECT statements, the 
MOVE PDS statement can be used to merge selected members of several 
partitioned data sets or to delete members. 

If IEHMOVE is used to allocate space for an output partitioned data set, the 
MOVE PDS statement can be used to expand a partitioned directory. 

If the receiving volume contains a partitioned data set with the same name, the 
two data sets are merged. The source data set is scratched. 

The format of the MOVE PDS statement is: 



[label] MOVE 



PDS= name 

,TO = device = serial 

[ { ,FROM = device = serial] 
{,CVOL=dew'ce=seria/}] 

[,EXPAND=nn] 

[,UNCATLG] 

[,RENAME=name] 

[,FROMDD=ddname] 

[,TODD=ddname] 



where: 



PDS= name 

specifies the fully qualified name of the partitioned data set to be moved. 

TO = device = serial 

specifies the device type and volume serial number of the volume to which the 
partitioned data set is to be moved. The list parameter may be used when 
unloading a partitioned data set that must span tape volumes. 

FROM = device = serial 

specifies the device type and volume serial number of the volume on which the 
partitioned data set currently resides, if it is not cataloged. If the data set is 
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COPY PDS Statement 



cataloged, FROM should not be written. FROM=device=list may be used when 
loading a PDS. 

CVOL= device=serial 

specifies the device type and volume serial number of the volume on which the 
catalog search for the partitioned data set is to begin. If neither FROM nor 
CVOL is written, the partitioned data set is assumed to be cataloged on the 
system residence volume. 

EXPAND =nn 

specifies the number of 256-byte records (up to 99 decimal) to be added to 
the directory of the specified partitioned data set. EXPAND will be ignored if 
space is previously allocated. 

UNCATLG 

specifies that the catalog entry pertaining to the source partitioned data set is 
to be removed. This parameter should be used only if the source data set is 
cataloged. If the volume is identified by FROM, UNCATLG is ignored. 

REN AME= name 

specifies that the data set is to be renamed, and indicates the new name. 

FROMDD=ddname 

specifies the name of a DD statement from which DCB and LABEL information 
are obtained. This parameter, which is valid for unloaded partitioned data sets 
on tape volumes, describes the mode and label of the magnetic tape and, in 
addition, must include the DCB attributes of the unloaded data set 
(RECFM=FB,LRECL=80,BLKSIZE=800). 

TODD =ddname 

specifies the name of a DD statement from which DCB and LABEL information 
are obtained. This parameter, which is valid for partitioned data sets to be 
unloaded to tape volumes, describes the mode and label of the magnetic tape 
on which the unloaded data set is to reside and, in addition, must include the 
DCB attributes of the unloaded data set (RECFM=FB,LRECL=80,BLKSIZE=800). 

The FROMDD and TODD parameters can be omitted for 800 bits per inch, 9-track 
tapes with standard labels on single density units or for 1600 bits per inch, 
9-track tape with standard labels on dual density units. 

Note: MOVE PDS causes the specified catalog to be updated automatically unless 
UNCATLG is specified. 



The COPY PDS statement is used to copy partitioned data sets. When used in 
conjunction with INCLUDE, EXCLUDE, REPLACE, or SELECT statements, the 
COPY PDS statement can be used to merge selected members of several 
partitioned data sets or to delete members. 

If IEHMOVE is used to allocate space for an output partitioned data set, the COPY 
PDS statement can be used to expand a partitioned directory. 

If the receiving volume already contains a partitioned data set with the same 
name, the two are merged. 
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The format of the COPY PDS statement is: 

[label] COPY PDS = name 

,TO = device = serial 

[ { ,FROM = device = serial } 

{,CVOL=dev/ce=ser/a/}] 

[,EXP AND =nn] 

[,UNCATLGJ 

[,CATLG] 

[,RENAME=name] 

[,FROMDD =ddname] 

[,TODD=ddname] 

where: 

PDS = name 

specifies the fully qualified name of the partitioned data set to be copied. 

TO = device — serial 

specifies the device type and volume serial number of the volume to which the 
partitioned data set is to be moved. The list value may be used when 
unloading a partitioned data set that must span tape volumes. 

FROM =device=serial 

specifies the device type and volume serial number of the volume on which the 
partitioned data set currently resides, if it is not cataloged. If the data set is 
cataloged, FROM should not be written. FROM = device = list may be used when 
loading a PDS. 

C VOL =device=serial 

specifies the device type and volume serial number of the volume on which the 
catalog search for the partitioned data set is to begin. If neither FROM nor 
CVOL is written, the partitioned data set is assumed to be cataloged on the 
system residence volume. 

EXPAND =nn 

specifies the number of 256-byte records (up to 99 decimal) to be added to 
the directory of the specified partitioned data set. EXPAND cannot be specified 
if space is previously allocated. 

UNCATLG 

specifies that the catalog entry pertaining to the source partitioned data set is 
to be removed. This parameter should be used only if the source partitioned 
data set is cataloged. UNCATLG is ignored if the volume is identified by FROM. 

CATLG 

specifies that the copied partitioned data set is to be cataloged on the 
receiving volume if it is a direct access volume. If a catalog does not exist on 
the receiving volume, a new catalog is created. 

RENAME == name 

specifies that the data set is to be renamed, and indicates the new name. 

FROMDD =ddname 

specifies the name of a DD statement from which DCB and LABEL information 
are obtained. This parameter, which is valid for unloaded partitioned data sets 
residing on magnetic tape volumes, describes the mode and label of the 
magnetic tape and, in addition, must include the DCB attributes of the 
unloaded data set (RECFM=FB,LRECL=80,BLKSIZE=800). 



20-20 OS/VS Utilities 



TODD=ddname 

specifies the name of a DD statement from which DCB and LABEL information 
are obtained. This parameter, which is valid for partitioned data sets to be 
unloaded to magnetic tape volumes, describes the mode and label of the 
magnetic tape on which the unloaded data set is to reside and, in addition, 
must include the DCB attributes of the unloaded data set 
(RECFM=FB,LRECL=80,BLKSIZE=800). 

The FROMDD and TODD parameters can be omitted for 800 bits per inch, 9-track 
tapes with standard labels on single density units or for 1600 bits per inch, 
9-track tape with standard labels on dual density units. 

Note: The source partitioned data set remains cataloged unless UNCATLG is 
specified. 



MOVE CATALOG Statement 



The MOVE CATALOG statement is used to move the entries of a catalog without 
moving the data sets associated with those entries. Certain entries can be 
excluded from the operation by means of the EXCLUDE statement. If the 
receiving volume contains a catalog, the source catalog entries are merged with it. 

The format of the MOVE CATALOG statement is: 

[label] MOVE CATALOG[= name] 
TO = device = serial 
[{,CVOL=dew'ce = serial] 
{, FROM = device= serial } ] 

[,FROMDD=ddname] 
[,TODD=ddname] 

where: 

CATALOG[= name] 

specifies the catalog entries to be moved. If name, which is a fully qualified 
name, is not coded, all entries in the catalog are to be moved. If name is 
coded, all catalog entries whose names are qualified by this name are moved. 
If the name is a fully qualified data set name, only the catalog entry that 
corresponds to that data set is moved. 

TO = device =ser/a/ 

specifies the device type and volume serial number of the volume to which the 
specified catalog entries are to be moved. 

C VOL = device = serial 

specifies the device type and volume serial number of the volume on which the 
search for the catalog is to begin. If both FROM and CVOL are omitted, the 
catalog is assumed to reside on the system residence volume. 

FROM = device = serial 

specifies the device type and volume serial number of the volume on which an 
unloaded version of the catalog resides. If neither FROM nor CVOL is coded, 
the catalog is assumed to reside on the system residence volume. 

FROMDD =ddname 

specifies the name of a DD statement from which DCB and LABEL information 
are obtained. This parameter, which is valid for unloaded catalogs residing on 
magnetic tape volumes, describes the mode and label of the magnetic tape 
and, in addition, must include the DCB attributes of the unloaded catalog 

(RECFM=FB,LRECL=80,BLKSIZE=800). 
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TODD=ddname 

specifies the name of a DD statement from which DCB and LABEL information 
are obtained. This parameter, which is valid for catalogs to be unloaded to 
magnetic tape volumes, describes the mode and label of the magnetic tape on 
which the unloaded catalog is to reside and, in addition, must include the DCB 
attributes of the unloaded catalog (RECFM=FB,LRECL=80,BLKSIZE=800). 

The FROMDD and TODD parameters can be omitted for 800 bits per inch, 9-track 
tapes with standard labels on single density units or for 1600 bits per inch, 
9-track tape with standard labels on dual density units. 



COPY CATALOG Statement 



The copy CATALOG statement is used to copy the entries in a catalog without 
copying the data sets associated with these entries. Certain entries can be 
excluded from a copy operation with the EXCLUDE statement. If the receiving 
volume contains a catalog, the source catalog is merged with it. 

The format of the COPY CATALOG statement is: 

[label] COPY CATALOG! = name] 
,TO = device = serial 
[{,CVOL=dewce=ser/a/} 
{,FROM=deWce= serial}] 
[,FROMDD=ddname] 
[,TODD=ddname] 

where: 

CATALOG[=name] 

specifies the catalog entries to be copied. If name, which is a fully qualified 
name, is not coded, all entries in the catalog are to be copied. If name is 
coded, all catalog entries whose names are qualified by this name are copied. 
If the name is a fully qualified data set name, only the catalog entry that 
corresponds to that data set is copied. 

TO=dev»'ce=ser;'a/ 

specifies the device type and volume serial number of the volume onto which 
the specified catalog entries are to be copied. 

C VOL = device = serial 

specifies the device type and volume serial number of the volume on which the 
search for the catalog is to begin. 

FROM =dev/ce= serial 

specifies the device type and volume serial number of the volume on which an 
unloaded version of the catalog resides. If neither FROM nor CVOL is written, 
the catalog is assumed to reside on the system residence volume. 

FROMDD=ddname 

specifies the name of a DD statement from which DCB and LABEL information 
is obtained. This parameter, which is valid for unloaded catalogs residing on 
tape volumes, describes the mode and label of the tape and, in addition, must 
include the DCB attributes of the unloaded catalog 
(RECFM==FB,LRECL=80,BLKSIZE=800). 

TODD=ddname 

specifies the name of a DD statement from which DCB and LABEL information 
are obtained. This parameter, which is valid for catalogs to be unloaded onto 
tape volumes, describes the mode and label of the tape volume on which the 
unloaded catalog is to reside and, in addition, must include the DCB attributes 
of the unloaded catalog (RECFM=FB,LRECL=80,BLKSIZE=800). 
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MOVE VOLUME Statement 



COPY VOLUME Statement 



The FROMDD and TODD parameters can be omitted for 800 bits per inch, 9-track 
tapes with standard labels on single density units or for 1600 bits per inch, 
9-track tape with standard labels on dual density units. 



The MOVE VOLUME statement is used to move all the data sets residing on a 
specified volume. Catalog entries associated with the data sets remain unchanged. 
Data sets to be moved must reside on direct access volumes. 

The format of the MOVE VOLUME statement is: 

[label] MOVE VOLUME=deWce=ser/a/ 
,TO=dev/ce=/»st 
[,PASSWORD] 

[,TODD=ddname] 

where: 

VOLUME=deWce=seria/ 

specifies the device type and volume serial number of the source volume. 

TO=dev/'ce=//st 

specifies the volume or volumes to which the data sets are to be moved. 

PASSWORD 

specifies that password protected data sets are to be included in the operation. 
If PASSWORD is omitted, only data sets that are not protected are moved. 

TODD=ddname 

specifies the name of a DD statement from which DCB and LABEL information 
are obtained. This parameter, which is valid for data sets to be moved to tape 
volumes, describes the mode and label of the receiving tape volume. TODD can 
be omitted for 800 bits per inch, 9-track tapes with standard labels on single 
density units or for 1600 bits per inch, 9-track tape with standard labels on 
dual density units. 



The COPY VOLUME statement is used to copy all the data sets residing on a 
specified volume. Catalog entries associated with the data sets remain unchanged. 
Data sets to be copied must reside on direct access volumes. 

The format of the COPY VOLUME statement is: 

[label] COPY VOLUME=deWce=ser»a/ 
,TO=deWce=/»st 
[.PASSWORD] 
[,CATLG] 

[,TODD=ddname] 

where: % 

VOLUME = device = serial 

specifies the device type and volume serial number of the source volume. 

TO=dew'ce=//st 

specifies the volume or volumes to which the data sets are to be copied. 

PASSWORD 

specifies that password protected data sets are to be included in the operation. 
If PASSWORD is omitted, only data sets that are not protected are copied. 
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INCLUDE Statement 



CATLG 

specifies that all copied data sets are to be cataloged in a SYSCTLG (system 
catalog) data set on the direct access receiving volume. If a catalog does not 
exist on the receiving volume, it is created. 

TODD =ddname 

specifies the name of a DD statement from which DCB and LABEL information 
are obtained. This parameter, which is valid for data sets to be copied to 
magnetic tape volumes, describes the mode and label of the receiving magnetic 
tape volume. TODD can be omitted for 800 bits per inch, 9-track tapes with 
standard labels on single density units or for 1600 bits per inch, 9-track tape 
with standard labels on dual density units. 

If CATLG is specified and the source volume contains a SYSCTLG data set, error 
messages indicating that an inconsistent index structure exists are issued when the 
source SYSCTLG data set entries are merged into the catalog on the receiving 
volume. (Because the SYSCTLG data set is the last to be copied, only those 
entries representing cataloged data sets not residing on the source volume are 
copied into a receiving volume's SYSCTLG data set; entries representing all data 
sets residing on the source volume have already been made in the receiving 
SYSCTLG data set.) 



The INCLUDE statement is used to enlarge the scope of MOVE DSGROUP, COPY 
DSGROUP, MOVE PDS, or COPY PDS statements by including a member or a data 
set not explicitly defined in those statements. The INCLUDE statement follows the 
MOVE or COPY statement whose function it modifies. Any number of INCLUDE 
statements can modify a MOVE or COPY statement. For a PDS, the INCLUDE 
statement is invalid when data is unloaded or when unloaded data is moved or 
copied. 

The format of the INCLUDE statement is: 



[label] INCLUDE 



DSNAME=name 
[MEMBER= membername] 

[{,FROM=dew"ce=//st} 
{ ,C VOL = device = ser ial } ] 



where: 



DSNAME==name 

specifies the fully qualified name of a data set. When the INCLUDE statement 
modifies a MOVE DSGROUP or COPY DSGROUP statement, the named data set 
is included in the group. When the INCLUDE statement modifies a MOVE PDS 
or COPY PDS statement, either the entire named partitioned data set or a 
member of the data set is included in the operation. 

MEMBER = membername 

specifies the name of a member of the partitioned data set named in the 
dsname parameter. This member is merged with the partitioned data set that 
is moved or copied. Its record characteristics must be compatible with those of 
the data set with which it is being merged. The data set containing this 
member is not scratched, regardless of the operation. This parameter is valid 
and required only when the INCLUDE statement modifies a MOVE PDS or 
COPY PDS statement. 
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EXCLUDE Statement 



SELECT Statement 



FROM=dewce= list 

specifies the volume or volumes on which the data set resides, if the data set is 
not cataloged. If the data set is cataloged, FROM should not be specified. If 
both FROM and CVOL are omitted, the specified data set is assumed to be 
cataloged on the system residence volume. 

C VOL = device = serial 

specifies the device type and volume serial number of the volume on which the 
catalog search for the data set is to begin. If both FROM and CVOL are 
omitted, the specified data set is assumed to be cataloged on the system 
residence volume. 



The exclude statement is used to restrict the scope of move DSGROUP, COPY 

DSGROUP, MOVE PDS, COPY PDS, MOVE CATALOG, or COPY CATALOG 

statements by excluding a specific portion of data defined in those statements. 

Partitioned data set members excluded from a MOVE PDS operation cannot be 
recovered (the source data set is scratched). Any number of EXCLUDE 
statements can modify a MOVE PDS or COPY PDS statement. 

Source data sets or catalog entries excluded from a MOVE DSGROUP or MOVE 
CATALOG operation remain available. Only one EXCLUDE statement can modify 

a MOVE DSGROUP, COPY DSGROUP, MOVE CATALOG, or COPY CATALOG 
statement. The EXCLUDE statement is invalid when data is unloaded or when 
unloaded data is moved or copied. 

The format of the EXCLUDE statement is: 



[label] EXCLUDE 



{DSGROUP= name] 

{ MEMBER = membername } 



where: 



DSGROUP= name 

specifies a qualified name. If the EXCLUDE statement modifies a MOVE 
DSGROUP or COPY DSGROUP statement, all data sets whose names are 
qualified by this name are excluded from the operation. If the EXCLUDE 
statement modifies a MOVE CATALOG or COPY CATALOG statement, all 
catalog entries whose names are qualified by this name are excluded from the 
operation. 

MEMBER = membername 

identifies a member to be excluded from the partitioned data set being moved 
or copied when the EXCLUDE statement modifies a MOVE PDS or COPY PDS 
statement. 



The select statement is used with the MOVE PDS or copy PDS statement to 
select members to be moved or copied, and to optionally rename these members. 
The SELECT statement cannot be used with either the EXCLUDE or REPLACE 
statement to modify the same MOVE PDS or COPY PDS statement. The SELECT 
statement is invalid when data is unloaded or when unloaded data is moved or 
copied. 
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REPLACE Statement 



IEHMOVE Examples 



The format of the SELECT statement is: 

[label] SELECT {MEMBER=(name[,name...)} 

{MEMBER=((name,newname)[,(name,newname)]. . .)} 

where: 

MEMBER == (name[,name] ...) 

identifies the members to be moved or copied. These members belong to the 
partitioned data set identified in the preceding MOVE PDS or COPY PDS 
statement. 

MEMBER= ((name,newname)[,(name, newname)]. . . ) 

identifies the members to be moved or copied and gives the new name for 
each member. 



The REPLACE statement is used with a MOVE PDS or COPY PDS statement to 
exclude a member from the operation and replace it with a member from another 
partitioned data set. The new member must have the same name as the old 
member and must possess compatible record characteristics. Any number of 
REPLACE statements can modify a MOVE PDS or COPY PDS statement. The 
REPLACE statement is invalid when data is unloaded or when unloaded data is 
moved or copied. 

The format of the REPLACE statement is: 



[label] REPLACE 



DSNAME=name 
MEMBER=name 

[{,FROM=deWce=seria/} 
{,CVOL=deWce=ser»'a/}] 



where: 



DSNAME=name 

specifies the fully-qualified name of the partitioned data set that contains the 
new member. 

MEMBER == name 

specifies the name of the member. 

FROM = device=serial 

specifies the device type and volume serial number of the volume that contains 
the partitioned data set named in the DSNAME parameter. If the partitioned 
data set is cataloged, FROM should not be specified. 

C VOL = de vice = serial 

specifies the device type and volume serial number of the control volume on 
which the catalog search for the partitioned data set containing the new 
member is to begin. 

If neither FROM nor CVOL is specified, the partitioned data set is assumed to be 
cataloged on the system residence volume. 



The following examples illustrate some of the uses of IEHMOVE. Table 20-9 can 
be used as a quick reference guide to IEHMOVE examples. The numbers in the 
"Example" column point to the examples that follow. 
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Table 20-9. iehmove : 


Example Directory 




Operation 


Data Set 
Organization 


Device 


Comments 


Example 


MOVE 


Sequential 


3330 Disk, 
2314 Disks 


Source volume is demounted after 
job completion. Two mountable 
disks. 


l 


COPY 


Sequential 


3330 Disk, 
2314 or 
2319 Disks 1 


Three cataloged sequential data 
sets are to be copied. The 2314 
or 2319 are mountable. 


2 


MOVE 


Data set group 2314 Disk, 
3330 Disk, 
2314 Disk 


Data set group is to be moved. The 
2314 disks are mountable. 


3 


MOVE 


Partitioned 


3330 Disk, 
2314 Disks 


A partitioned data set is to be 
moved; a member from another 
PDS is to be merged with it. 


4 


MOVE and 
CATALOG 


Catalog 


2314 Disk, 
3330 Disk, 
2314 Disk 


Catalog is to be moved from 
system residence volume to second 
volume. Source catalog is scratched 
from system residence volume. 


5 


MOVE 


Catalog 


3330 Disk, 
2314 Disk 


Selected catalog entries are to be 
moved from system residence to 
a second volume. SYSCTLG is 
scratched. 


6 


MOVE 


Volume 


3330 Disk, 
2314 Disks 


Volume of data sets is to be moved. 


7 


MOVE 


Partitioned 


3330 Disk, 
2314 Disks 


A data set is to be moved to a 
volume on which space was 
previously allocated. 


8 


MOVE 


Partitioned 


3330 Disk, 
2314 Disk 


Three data sets are to be moved 
and unloaded to a volume on which 
space was previously allocated. 


9 


MOVE 


Sequential 


2314 Disk, 
2400 Tape 


A sequential data set is to be 
unloaded to an unlabeled 9-track 
tape volume. 


10 


MOVE 


Sequential 


3330 Disk, 
2314 Disk, 
2400 Tape 


Unloaded data sets are to be 
loaded from a single volume. 


11 


COPY 


Sequential 


2314 Disk, 
2400 Tape 


Data sets are to be copied from 
separate source volumes. 


12 


COPY 


Partitioned 


2400 Tape, 
2314 Disks 


Unloaded data sets are to be 
loaded from unlabeled tape to a 
specific device. 


13 


1 Note that the 2319 disk is functionally equivalent to the 2314 disk; to use the 2319 
2314 in the control statement. 


', specify 



In this example, three data sets (SEQSETi, SEQSET2, and SEQSET3) are to be 
moved from a disk volume to three separate disk volumes. Each of the three 
receiving volumes is mounted when it is required by IEHMOVE. The source data 
sets are not cataloged. Space is allocated by IEHMOVE. 
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The example follows: 

//MOVEDS JOB 09#550,GREEN 

// EXEC PGM= IEHMOVE 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD UNIT=3330,VOLUME=SER=333000,DISP=OLD 

//DD1 DD UNIT=2314,VOLUME=SER=1 1 1 1 1 1 ,DISP=OLD 

//DD2 DD UNIT=( 2314, , DEFER ),DISP=OLD, 

// VOLUME=( PRIVATE, ,SER=( 231400 ) ) 

//DD3 DD VOLUME=( PRIVATE, RETAIN, SER=( 23141 1 ) ), 

// UNIT=2314,DISP=OLD 

//SYSIN DD * 

MOVE 

MOVE 

MOVE 
/* 



DSNAME=SEQSET1 , TO=23 1 4=23 1 400 , FROM=23 1 4=23 1 4 1 1 
DSNAME=SEQSET2 , TO=23 1 4=23 1 412, FROM=23 1 4=23 1 41 1 
DSNAME=SEQSET3 , TO=23 1 4=231 413, FROM=23 1 4=23 1 4 1 1 



The control statements are discussed below: 

• SYSUTi dd defines the device that is to contain the work data set. 

• DDl DD defines the system residence device. 

• DD2 DD defines the mountable device on which the receiving volumes will be 
mounted as they are required. 

• DD3 DD defines a mountable device on which the source volume is to be 
mounted. Because the RETAIN subparameter is included, the volume remains 
mounted until the job has completed. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• MOVE moves the source data sets to volumes 231400, 231412, and 231413, 
respectively. The source data sets are scratched. 



In this example, three cataloged data sets are to be copied to a 2314 or 2319 
volume. Note that the 2319 is functionally equivalent to the 2314; to use a 2319, 
specify 2314 in the control statement. Space is allocated by IEHMOVE. The 
catalog is not updated. The source data sets are not scratched. 



The example follows: 

//COPYPDS JOB 
// EXEC 

//SYSPRINT DD 



//SYSUT1 


DD 


//DD1 


DD 


//DD2 


DD 


//DD3 


DD 


//SYSIN 


DD 




COPY 




COPY 




COPY 



/* 



09#550, GREEN 

PGM= IEHMOVE 

SYSOUT=A 

UNIT=23 1 4 , VOLUME=SER=2 3 1400, DISP=OLD 

UNIT=3330,VOLUME=SER=1 11111 ,DISP=OLD 

UNIT=23 1 4 , VOLUME=SER=23 1 400 , DISP=OLD 

UNIT=23 1 4 , VOLUME=SER=23 1 40 1 , DISP=OLD 

* 

DSNAME=SEQSET1 , TO=23 1 4=23 1 40 1 
DSNAME=SEQSET3 , TO=23 1 4=23 1 40 1 
DSNAME=SEQSET4 , TO=23 1 4=23 1 40 1 



The control statements are discussed below: 

• SYSUTI DD defines the device that is to contain the work data set. 

• DDl DD defines the system residence device. 

• DD2 DD defines a mountable device on which the source volume is mounted. 

• DD3 DD defines a mountable device on which the receiving volume is 
mounted. 

• SYSIN DD defines the control data set which follows in the input stream. 
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IEHMOVE Example 4 



• COPY copies the source data sets onto volume 231401. 

Note: This example implies that the cataloged source data sets all exist on a 2314 
volume. If the data sets existed on a volume or volumes other than a 2314, the 
necessary DD statements would have to be included in this example to define the 
applicable mountable device(s). 



In this example, the data set group A.B.C — which comprises data set A.B.C.X, 
a.b.c.y, and A.B.C. z — is moved from two 2314 volumes onto a third volume. 
Space is allocated by IEHMOVE. The catalog is updated to refer to the receiving 
volume. The source data sets are scratched. 



The example follows: 



//MOVEDSG 


JOB 


// 


EXEC 


//SYSPRTNT 


DD 


//SYSUTI 


DD 


//DD1 


DD 


//DD2 


DD 


//DD3 


DD 


//DD4 


DD 


//SYSIN 


DD 


MOVE 



/* 



09#550, GREEN 

PGM= IEHMOVE 

SYSOUT=A 

UN1T-23 1 4 , VOLUME=SER=23 1401, DISP=OLD 

UNIT=3330,VOLUME=SER=1 11111 ,D1SP=0LD 

UNIT-2314,VOLUME=SER-2 3 1401 , DISP^OLD 

UNIT-^23 1 4 , VOLUME=SER=2 3 I 4 1 , DTSP=OLD 

UNIT=23 1 4 , VOLUME=SER=23 1411, DISP=OLD 

* 

USGROUP=A . B . C , TO=2 3 1 4-2 3 14 01 



The control statements are discussed below: 

• SYSUTI DD defines the device that is to contain the work data set. 

• DDl dd defines the system residence device. 

• DD2 DD defines a mountable device on which the receiving volume is to be 
mounted. 

• DD3 DD defines a mountable device on which one of the source volumes is to 
be mounted. 

• DD4 DD defines a mountable device on which one of the source volumes is to 
be mounted. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• MOVE moves the specified data sets to volume 231401. 

Note: This example can be used to produce the same result without the use of 
the DD4 DD statement, using one less mountable 2314 device. With DD3 and 
DD4, both of the source volumes are mounted at the start of the job. With DD3 
only, the 231410 volume is mounted at the start of the job. After the 231410 
volume is processed, the utility requests that the operator mount the 231411 
volume. In this case the DD3 statement is coded: 

//DD3 DD UNri=(2314,,DEFER),DISP=OLD,VOLUME=:(PRIVATE,, 
// SER=(231410» 



In this example, a partitioned data set (PARSETi) is to be moved to a disk 
volume. In addition, a member (PARMEM3) from another partitioned data set 
(PARTSET2) is to be merged with the source members on the receiving volume. 
The source partitioned data set (PARTSETD is scratched. Space is allocated by 

IEHMOVE. 
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IEHMOVE Example 5 



//MOVEPDS 

// 

//SYSPRINT 

//SYSUT1 

//DD1 

//DD2 

//DD3 

//DD4 

//SYSIN 

MOVE 
■INCLUDE 
/* 



JOB 09#550, GREEN 
EXEC PGM= IEHMOVE 
DD SYSOUT=A 

DD UNIT=3330,VOLUME=SER=333000,DISP=OLD 
DD UNIT=2314,VOLUME=SER=1 11111 ,DISP=OLD 
DD UNIT=23 1 4 , VOLUME=SER=23 1 400 , DISP=OLD 
DD UNIT=23 1 4 , VOLUME=SER=23 1 410, DISP=OLD 
DD UNIT=23 1 4 , VOLUME=SER=23 1 420 , DISP=OLD 
DD * 
PDS=PARTSET1 , TO=23 1 4=23 1 420 , FROM=23 1 4=23 1 400 
DSNAME=PARTSET2 , MEMBER=PARMEM3 , FROM=23 1 4=23 1 4 1 



The control statements are discussed below: 

• SYSUTl DD defines the device that is to contain the work data set. 

• DDl DD defines the system residence device. 

• The DD2, DD3, and DD4 DD statements define mountable devices that are to 
contain the two source volumes and the receiving volume. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• MOVE defines the source partitioned data set, the volume that contains it, and 
its receiving volume. 

• include includes a member from a second partitioned data set in the 
operation. 



In this example, the SYSCTLG data set is to be moved from the system residence 
volume to a mountable 2314 volume. Space is allocated by IEHMOVE. The source 
catalog is scratched from the system residence volume. 

The example follows: 

//MOVECAT1 JOB 09 #5 50, GREEN 
// EXEC PGM= IEHMOVE 

//SYSPRINT DD SYSOUT=A 



//SYSUT1 DD 
//DD1 DD 

//DD2 DD 

//SYSIN DD 

MOVE 
/* 



UNIT=23 1 4 , VOLUME=SER=23 1 400 , DISP=OLD 
UNIT=3330,VOLUME=SER=1 11111 ,DISP=OLD 
UNIT=23 1 4 , VOLUME=SER=222222 , DISP=OLD 
* 

CATALOG, TO=2 3 14=222 222 



The control statements are discussed below: 

• SYSUTl DD defines the device that is to contain the work data set. 

• DDl DD defines the system residence device. The system residence volume 
contains the catalog to be moved. 

• DD2 DD defines the mountable device on which the receiving volume is to be 
mounted. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• MOVE specifies the move operation and defines the receiving volume. 
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IEHMOVE Example 7 



In this example, the data set group A.B.C — which comprises data sets entries 
A.B.C.x, A.B.C.Y, and A.B.C.z — is to be moved from the sysctlg data set to a 
mountable 2314 volume. If no catalog exists on the 2314 volume, one is created; 
if a catalog does exist, the specified entries are merged into it. The last INDEX of 
all entries in the source SYSCTLG is scratched. The work data set is deleted when 
the job step is completed. 

The example follows: 

//MOVECAT2 JOB 09# 550, GREEN 
// EXEC PGM= IEHMOVE 



//SYSPRINT DD 



//SYSUT1 


DD 


//DD1 


DD 


//DD2 


DD 


//SYSIN 


DD 




MOVE 



/* 



SYSOUT=A 

UNIT=23 1 4 , VOLUME=SER=23 1 402 , DISP=OLD 

UNIT=3330,VOLUME=SER=1 11111 ,DISP=OLD 

UNIT=23 1 4 , VOLUME=SER=23 1 402 , DISP=OLD 

* 

CATALOG=A. B . C , TO=23 1 4=23 1 402 



The control statements are discussed below: 

• SYSUTl DD defines the device that is to contain the work data set. (Because 
IEHMOVE deletes the work data set at the completion of the program, it can 
be contained on the receiving volume, provided there is room for it.) 

• DDl DD defines the system residence device. The system residence volume 
contains the entries to be moved. 

• DD2 DD defines the mountable device on which the receiving volume is to be 
mounted. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• MOVE specifies a move operation for selected entries and defines the receiving 
volume. 



In this example, a volume of data sets is to be moved to a 2314 volume. All data 
sets that are successfully moved are scratched from the source volume; however, 
any catalog entries pertaining to those data sets are not changed. Space is 
allocated by IEHMOVE. The work data set is deleted when the job step is 
completed. 

The example follows: 



//MOVEVOL 

// 

//SYSPRINT DD 

//SYSUT1 DD 

//DD1 

//DD2 

//DD3 

//SYSIN 



JOB 09#550, GREEN 
EXEC PGM= IEHMOVE 



DD 
DD 
DD 
DD 
MOVE 



/* 



SYSOUT=A 

UNIT=23 1 4 , VOLUME=SER=23 1 400 , DISP=OLD 

UNIT=3330,VOLUME=SER=1 11111 ,DISP=OLD 

UNIT=23 1 4 , VOLUME=SER=23 1 400 , DISP=OLD 

UNIT=23 1 4 , VOLUME=SER=23 1 40 1 , DISP=OLD 

* 

VOLUME=23 1 4=23 1 40 1 , TO=23 1 4=23 1 400 , PASSWORD 



The control statements are discussed below: 

• SYSUTl DD defines the device that is to contain the work data set. The work 
data set is removed from the receiving volume when the job step is completed. 

• DDl DD defines the system residence device. 

• DD2 DD defines the mountable device on which the receiving volume is to be 
mounted. 
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• DD3 DD defines a mountable device on which the source volume is to be 
mounted. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• MOVE specifies a move operation for a volume of data sets and defines the 
source and receiving volumes. This statement also indicates that 
password-protected data sets are to be included in the operation. 

Note: IEHPROGM can be used to uncatalog catalog entries pertaining to source 
data sets and to catalog the moved versions of those data sets. 
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In this example, a partitioned data set is to be moved to a 2314 volume on which 
space has been previously allocated for the data set. The source data set is 
scratched. The work data set is deleted when the job step is completed. 

The example follows: 

//ALLOCATE JOB 09#550, GREEN 

// EXEC PGM= IEHPROGM 

//SYSPRINT DD SYSOUT=A 

//SET1 DD DSNAME=PDSSET1 , UNIT=23 14 ,DISP=( NEW, KEEP ), 

// VOLUME=SER=231401 ,SPACE=(TRK, ( 1 00 , 1 , 1 ) ) , 

// DCB=( RECFM=FB , LRECL=80 , BLKSIZE=2000 ) 

//SYSIN DD * 

/* 

// EXEC PGM=IEHMOVE 

//SYSPRINT DD SYSOUT=A 

UNIT=2 3 1 4 , VOLUME=SER=23 1 40 1 , DISP=OLD 
UNIT=3 330,VOLUME=SER=1 11111 ,DISP=OLD 
UNIT=23 1 4 , VOLUME=SER=23 1 40 1 , DISP=OLD 
UNIT=2 314, VOLUME=SER = 23 1 402 , DISP-OLD 



//SYSUT1 


DD 


//DD1 


DD 


//DD2 


DD 


//DD3 


DD 


//SYSIN 


DD 




MOVE 



PDS=PDSSET1 ,TO-23 14=23 1401 , FROM=23 1 4=23 1 402 



/> 



The IEHPROGM job step is used to allocate space for data set PDSSET1 on a 
2314 volume. 

The control statements are discussed below: 

SYSUTi DD defines the device that is to contain the work data set. The data 
set is removed from the receiving volume at the completion of the program. 

DDl DD defines the system residence device. 

DD2 DD defines the device on which the receiving volume is to be mounted. 

DD3 DD defines a mountable device on which the source volume is to be 
mounted. 

SYSIN DD defines the control data set, which follows in the input stream. 

MOVE specifies a move operation for the partitioned data set PDSSETl and 
defines the source and receiving volumes. 
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In this example, three partitioned data sets are to be moved from three separate 
source volumes to a 2314 volume. The source data set PDSSET3 is unloaded. 
(The record size exceeds the track capacity of the receiving volume.) The work 
data set is deleted when the job step is completed. 
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//SYSIN 


DD 


/* 




// 


EXEC 


//SYSPRINT DD 


//SYSUT1 


DD 


//DD1 


DD 


//DD2 


DD 


// VOLUME=(PRIV 


//DD3 


DD 


//SYSIN 


DD 




MOVE 




MOVE 




MOVE 



The example follows: 

//ALLOCATE JOB 09 #550, GREEN 

// EXEC PGM=IEHPROGM 

//SYSPRINT DD SYSOUT=A 

//SET1 DD DSNAME=PDSSET1 , UNIT=23 1 4 ,DISP=( NEW,KEEP ) , 

// VOLUME=SER=231401 , SPACE=( TRK, ( 50, 10,5 ) ) ,DCB=( RECFM=FB, 

// LRECL=80,BLKSIZE=1600 ) 

//SET2 DD DSNAME=PDSSET2,UNIT=2314,DISP=(NEW,KEEP), 

// VOLUME=SER=231401 , SPACE=( TRK, ( 25,5,5 ) ) , DCB=( RECFM=F, 

// LRECL=80,BLKSIZE=80 ) 

//SET3 DD DSNAME=PDSSET3,UNIT=2314,DISP=(NEW,KEEP), 

// VOLUME=SER=231401 ,SPACE=(TRK, ( 25,5 ) ) , DCB=( RECFM=U, 

// BLKSIZE=5000 ) 



PGM= IEHMOVE 
SYSOUT=A 

UNIT=23 1 4 , VOLUME=SER=23 1 401, DISP=OLD 
UNIT=3330,VOLUME=SER=1 11111 ,DISP=OLD 
UNIT=( 2314, , DEFER ),DISP=OLD, 
PRIVATE , , SER=( 231400)) 

UNIT=23 1 4 , VOLUME=SER=23 1 40 1 , DISP=OLD 
* 

PDS=PDSSET1 ,TO=23 14=23 1401 , FROM=23 1 4=23 1 400 
PDS=PDSSET2 , TO=23 1 4=23 1 40 1 , FROM=23 1 4=23 1 401 
PDS=PDSSET3 , TO=23 1 4=23 1 40 1 , FROM=23 1 4=23 1 402 
/* 

The IEHPROGM job step is used to allocate space for the partitioned data sets 
PDSSETl, PDSSET2, and PDSSET3 on the receiving volume. The SPACE parameter 
in the SET3 DD statement allocates space for a sequential data set. This is 
necessary to successfully unload the partitioned data set PDSSET3. The DCB 
attributes of PDSSET3 are: 

DCB=(RECFM=U,BLKSIZE=5000) 

The unloaded attributes are: 

DCB=(RECFM=FB,LRECL=80,BLKSIZE=800) 
The control statements are discussed below: 

• SYSUTl DD defines the device that is to contain the work data set. 

• DDl DD defines the system residence device. 

• DD2 DD defines a mountable device on which the source volumes are mounted 
as they are required. 

• DD3 DD defines a mountable device on which the receiving volume is 
mounted. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• MOVE specifies move operations for the partitioned data sets and defines the 
source and receiving volumes. 

Note: For a discussion on estimating space allocations, refer to OS/VS Data 
Management Services Guide, GC26-3783. 



In this example, a sequential data set is to be unloaded onto a 9-track, unlabeled 
tape volume (800 bits per inch). The work data set resides on the source volume 
and is deleted when the job step is completed. 
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The example follows: 



72 



09#550, GREEN 

PGM=IEHMOVE 

SYSOUT=A 

UNIT=23 1 4 , VOLUME=SER=23 1 400 , DISP=OLD 

UNIT=2314,VOLUME=SER=1 11111 ,DISP=OLD 

UNIT=23 1 4 , VOLUME=SER=23 1 400 , DISP=OLD 

UNIT=2400,VOLUME=SER=SCRTCH,DISP=OLD, 



//UNLOAD JOB 

// EXEC 

//SYSPRINT DD 

//SYSUT1 DD 

//DD 1 DD 

//DD2 DD 

//TAPEOUT DD 

// DCB=(DEN=2,RECFM=FB,LRECL=80,BLKSIZE=800 ), 

// LABEL- ( ,NL) 

//SYSIN DD * 

MOVE DSNAME=SEQSET1 ,TO=2400=SCRTCH, C 

FROM=23 1 4=23 1 400 , TODD=TAPEOUT 
/* 

The control statements are discussed below: 

• SYSUTi DD defines the device that is to contain the work data set. 

• DDi DD defines the system residence device. 

• DD2 DD defines a mountable device on which the source volume is mounted. 

• TAPEOUT DD defines a mountable device on which the receiving tape volume 
is mounted. This statement also provides label and mode information. 

• SYSIN DD defines the control data set which follows in the input stream. 

• MOVE moves the sequential data set SEQSETl from a 2314 volume to the 
receiving tape volume. The data set is unloaded. The TODD parameter in this 
statement refers to the TAPEOUT DD statement for label and mode 
information. 
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In this example, three unloaded sequential data sets are to be loaded from a 
labeled, 7 -track tape volume (556 bits per inch) to a 2314 volume. Space is 
allocated by IEHMOVE. The example assumes that the 2314 volume is capable of 
supporting the data sets in their original forms. 



The example follows: 



//LOAD JOB 09 # 550, GREEN 

// EXEC PGM=IEHMOVE 



72 



//SYSPRINT DD 
//SYSUT1 DD 
//DD1 DD 
//DD2 DD 
//TAPESETS DD 



SYSOUT=A 

UNIT=23 1 4 , VOLUME=SER 
UNIT=3330,VOLUME=SER= 
UNIT=23 1 4 , VOLUME=SER= 
DSNAME=UNLDSET1 ,UNIT= 
// VOLUME=SER=00 1 234 , DISP=OLD , LABEL=( 
// DCB= ( DEN= 1 , TRTCH=C ) 
//SYSIN DD * 

MOVE DSNAME=UNLDSET1 ,T0=23 

FROM=2400-2=( 001234, 1 ) 

MOVE DSNAME=UNLDSET2,TO=23 

FROM=2400-2=( 00 1 234 , 2 ) 

MOVE DSNAME=UNLDSET3,TO=23 

FROM=2400-2=( 001234,3 ) 

/* 



231400,DISP=OLD 

111111 ,DISP=OLD 

231400,DISP=OLD 

2400-2, 

1,SL), 



14=231400, 

, FROMDD=TAPESETS 

14=231400, 

, FROMDD=TAPESETS 

14=231400, 

, FROMDD=TAPESETS 



The control statements are discussed below: 

• SYSUTi DD defines the device that is to contain the work data set. 

• DDl DD defines the system residence device. 
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• DD2 DD defines a mountable device on which the receiving volume is 
mounted. 

• TAPESETS DD defines a mountable device on which the source volume is 
mounted. DCB information is provided in this statement. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• MOVE moves the unloaded data sets to the receiving volume. 

Note: To move a data set from a tape volume that contains more than one data 
set, you must specify the sequence number of the data set in the list field of the 
FROM or TO parameter on the utility control statement. 



In this example, two sequential data sets are to be copied from separate source 
volumes to a 2314 volume. Space is allocated by IEHMOVE. Only one 9-track 
tape unit is available for the operation. 

The example follows: 

72 

//DEFER JOB 09#550, GREEN 

// EXEC PGM= IEHMOVE 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD UNIT=2314,VOLUME=SER=231400,DISP=OLD 

//DD1 DD UNIT=2314,VOLUME=SER=1 1 1 1 1 1 ,DISP=OLD 

//DD2 DD UNIT=2314,VOLUME=SER=231400,DISP=OLD 

//TAPE1 DD DSNAME=SEQSET1 , UNIT=2400 ,DISP=OLD, 

// LABEL=( 2 , SL ) , VOLUME=SER=00 1 234 , DCB=( DEN=2 , RECFM=U , 

// BLKSIZE=2000 ) 

//TAPE2 DD DSNAME=SEQSET9,UNIT=AFF=TAPE1 ,DISP=OLD, 

// LABEL=( 4 , SL ) , VOLUME=SER=00 1 235 , DCB=( DEN=2 , RECFM=FB , 

// LRECL=80,BLKSIZE=400 ) 

//SYSIN DD * 

COPY DSNAME=SEQSET1 ,TO=23 14=23 1400, C 

FROM=2400=( 001234,2 ) , FROMDD=TAPE 1 
COPY DSNAME=SEQSET9,TO=23 14=23 1400, C 

FROM=2400=( 001235,4 ) , FROMDD=TAPE2 
/* 

The control statements are discussed below: 

• SYSUTl DD defines the volume that is to contain the work data set. 

• DDl DD defines the system residence device. 

• DD2 DD defines a mountable device on which the receiving volume is 
mounted. 

• TAPEi DD defines a mountable device on which the first volume to be 
processed is mounted. The source data set is the second data set on the 
volume. 

• TAPE2 DD defines a mountable device on which the second volume to be 
processed is mounted when it is required. The source data set is the fourth 
data set on the volume. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• COPY copies the data sets to the receiving volume. 

Note: To copy a data set from a tape volume that contains more than one data 
set, you must specify the sequence number of the data set in the list field of the 
FROM or TO parameter on the utility control statement. 
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In this example, three unloaded partitioned data sets residing on an unlabeled 
tape volume mounted on device 282 are copied to a 2314 volume mounted on 
device 191. 

The example follows: 

//LOAD JOB MEDDAUGH,PS40300439,MSGLEVEL=1 

// EXEC PGM=IEHMOVE 

//SYSPRINT DD SYSOUT=A 
SYSOUT=A 

UNIT= 191, VOLUME=SER=2 3 1 400 , DISP=OLD 
UNIT= 191, VOLUME=SER=23 1 400 , DISP=OLD 
UNIT=282 , VOLUME=SER=NLTAPE , DISP=OLD , LABEL=( , NL ) 



//SYSABEND DD 
//SYSUT1 DD 
//DD1 DD 
//TAPE1 DD 
//SYSIN DD 



/* 



COPY PDS=DSET1 , FROM=282 = ( NLTAPE, 1 ) , TO=1 9 1 =23 1 400 , FROMDD=TAPE1 
COPY PDS=DSET2,FROM=282=( NLTAPE, 2 ) , TO=1 9 1 =23 1 400 , FROMDD=TAPE1 
COPY PDS=DSET3 , FROM=282 = ( NLTAPE , 3 ) , TO= 191=231400, FROMDD=TAPE 1 

The control statements are discussed below: 

• SYSUTl DD defines the work data set. 

• TAPEl DD defines the source data sets. They are, in the order in which they 
reside on the volume, DSETl, DSET2, and DSET3. 

• DDi DD defines the receiving volume. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• COPY copies the unloaded partitioned data sets from the unlabeled tape to the 
receiving volume. 

Note: To copy data sets from an unlabeled tape, you must place a label in the list 
field of the FROM parameter of the utility control statement. Following this label,- 
the sequence numbers of the data sets must also be included in the same field. 
The unit address must appear in the device field of the FROM or TO parameter 
whenever you want to move from or copy to a specific device. 
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IEHMOVE Program for VS2 Release 2 



IEHMOVE is a system utility used to move or copy logical collections of operating 
system data. (See "Introduction" for general system utility information.) 

IEHMOVE can be used to move or copy: 

• A data set residing on from one to five volumes, with the exception of the 
SYSCTLG data set, ISAM data sets, and VSAM data spaces. 

• A volume of data sets. 

• Including or excluding data sets from a move or copy operation. 

The scope of a basic move or copy operation can be enlarged by: 

• Merging members from two or more partitioned data sets. 

• Including or excluding selected members. 

• Renaming moved or copied members. 

• Replacing selected members. 

If, for some reason, IEHMOVE is unable to successfully move or copy specified 
data, an attempt is made to reorganize the data and place it on the specified 
output device. The reorganized data — called an unloaded data set — is a sequential 
data set consisting of 80-byte blocked records that contain the source data and 
control information for subsequently reconstructing the source data as it 
originally existed. 

When an unloaded data set is moved or copied to a device that will support the 
data in its true form, the data is automatically reconstructed. For example, if the 
user attempts to move a partitioned data set to a tape volume, the data is 
unloaded to that volume. The user can re-create the data set simply by moving 
the unloaded data set to a direct access volume. 

CAUTION 

Before unloading your OS/VS Catalog be aware that IEHMOVE, running under 
VS2 Release 2, will not load a back-up copy for you. 

A move operation differs from a copy operation in that a move operation 
scratches source data if the data set resides on a direct access source volume and 
the expiration date has occurred, while a copy operation leaves source data 
intact. In addition, for cataloged data sets, a move operation updates the catalog 
to refer to the moved version (unless otherwise specified), while a copy operation 
leaves the catalog unchanged. 

Space can be allocated for a data set on a receiving volume either by the user 
(through the use of DD statements in a prior job step) or by IEHMOVE in the 
IEHMOVE job step. If the source data is unmovable (that is, if it contains location 
dependent code), the user should allocate space on the receiving volume using 
absolute track allocation to ensure that the data set is placed in the same relative 
location on the receiving volume as it was on the source volume. Unmovable 
data can be moved or copied if space is allocated by IEHMOVE, but the data will 
not be in the same location on the receiving volume as it was on the source 
volume. When data sets are to be moved or copied between unlike devices, a 
secondary allocation should be made to ensure that ample space is available on 
the receiving volume. 
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Space for a new data set cannot be allocated by the user under the following 
circumstances: 

• When the organization of the data set to be moved or copied is direct and the 
data set is not to be unloaded, iehmove cannot determine whether the new 
data set is empty. 

• When a partitioned data set is being moved or copied as part of a move or 
copy volume operation and the data set is not to be unloaded. If the user does 
preallocate a partitioned data set in this case, no merging takes place. 

If IEHMOVE performs the space allocation for the new data set, the space 
requirement information of the old data set (if available) is used. This space 
requirement information is obtained from the DSCB of the source data set, if it is 
on a direct access device, or the control information in the case of an unloaded 
data set. 

If space requirement information is available, IEHMOVE uses this information to 
derive an allocation of space for the receiving volume, taking into account the 
differences in device characteristics, such as track capacity and overhead factors. 
However, when data sets with variable or undefined record formats are being 
moved or copied between unlike devices, no assumption can be made about the 
space that each individual record needs on the receiving device. 

In general, when variable or undefined record formats are to be moved or copied, 
iehmove attempts to allocate sufficient space. This might cause too much space 
to be allocated under the following circumstances: 

• When moving or copying from a device with a relatively large block overhead 
to a device with a smaller block overhead, the blocks being small in relation to 
the block size. 

• When moving or copying from a device with a relatively small block overhead 
to a device with a larger block overhead, the blocks being large in relation to 
the block size. 

Note: Data sets with direct organization and variable or undefined record format 
always have the same amount of direct access space allocated by iehmove. This 
practice preserves any relative track addressing system that might exist within the 
data sets. 

Note: When a data set has more than three extents and the space requirement 
for the remaining extents is more than eleven times the secondary allocation 
quantity, the data set should be allocated before performing the copy operation. 

A move or copy operation results in: (1) a moved or copied data set, (2) no 
action, or (3) an unloaded version of the source data set. These results depend 
upon the compatibility of the source and receiving volumes with respect to: 

• Size of the volumes. 

• Data set organization (sequential, partitioned, or direct access). 

• Movability of the source data set. 

• Allocation of space on the receiving volume. 

Two volumes are compatible with respect to size if (1) the source record size 
does not exceed the receiving track size, or (2) the receiving volume supports the 
track overflow feature and the output is to be written with track overflow. (Refer 
to "Job Control Statements" for notes on the track overflow feature.) When 
using direct access organization, two volumes are compatible with respect to size 
if the source track capacity does not exceed the receiving track capacity. Direct 
access data sets moved or copied to a smaller device type or tape are unloaded. 
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If the user wishes to load an unloaded direct access data set, it must be loaded to 
the same device type from which it was originally unloaded. 

Table 21-1 shows the results of move and copy operations when the receiving 
volume is a direct access volume that is compatible in size with the source 
volume. The organization of the source data set is shown along with the 
characteristics of the receiving volume. 

Table 21-1. Move and Copy Operations — Direct Access Receiving Volume with Size 
Compatible with Source Volume 

Receiving Volume 
Characteristics 



Space allocated 
by IEHMOVE 
(movable data) 

Space allocated 
by IEHMOVE 
(immovable data) 

Space previously 
allocated, as yet 
unused 

Space previously 
allocated, partially 
used 



Sequential 
moved or copied 

moved or copied 

moved or copied 

no action 



Partitioned 
moved or copied 

moved or copied 

moved or copied 



moved or copied 
(merged) 



Direct Access 
moved or copied 



no action 



no action 



no action 



Table 21-2 shows the results of move and copy operations when the receiving 
volume is a direct access volume that is not compatible in size with the source 
volume. The organization of the source data set is shown along with the 
characteristics of the receiving volume. 

Table 21-2. Move and Copy Operations — Direct Access Receiving Volume with Size 
Incompatible with Source Volume 



Receiving Volume 
Characteristics 

Space allocated 

by IEHMOVE 

Space previously 
allocated, as yet 
unused 

Space previously 
allocated, partially 
used 



Sequential 
unloaded 

unloaded 
no action 



Partitioned 
unloaded 

unloaded 
no action 



Direct Access 
unloaded 

no action 
no action 



Table 21-3 shows the results of move and copy operations when the receiving 
volume is not a direct access volume. The organization of the source data set is 
shown along with the characteristics of the receiving volume. 

Table 21-3. Move and Copy Operations — Non-Direct Access Receiving Volume 



Receiving Volume 
Characteristics 

Movable data 

Unmovable data 



Sequential 
moved or copied 
unloaded 



Partitioned 

unloaded 

unloaded 



Direct Access 
unloaded 
no action 



Space cannot be previously allocated for a partitioned data set that is to be 
unloaded unless the SPACE parameter in the DD statement making the allocation 
implies sequential organization. Direct data sets cannot be previously allocated 
because they cannot be differentiated from partially used existing direct data sets. 

If a move or copy operation is unsuccessful, the source data remains intact. 
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Reblocking 



If a move or copy operation is unsuccessful and space was allocated by 
IEHMOVE, all data associated with that operation is scratched from the receiving 
direct access volume. If the receiving volume was tape, it will contain a partial 
data set. 

If a move or copy operation is unsuccessful and space was previously allocated, 
no data is scratched from the receiving volume. If, for example, IEHMOVE moved 
104 members of a 105 -member partitioned data set and encountered an 
input/output error while moving the 105th member: 

• The entire partitioned data set is scratched from the receiving volume if space 
was allocated by IEHMOVE. 

• No data is scratched from the receiving volume if space was previously 
allocated. In this case, after determining the nature of the error, the user need 
move only the 105th member into the receiving partitioned data set. 

If a sequential data set is to be moved or copied and space attributes are not 
available either through a previous allocation or from the data set control block 
belonging to the source data set, IEHMOVE makes a default space allocation. The 
default allocation consists of a primary allocation of 72,500 bytes of storage 
(data and gaps) and up to 14 secondary allocations of 36,250 bytes each. 

When moving or copying a data set group or a volume containing 
password-protected data sets, the user must provide the password each time a 
data set is opened or scratched. 

IEHMOVE always moves or copies any user labels associated with an input data 
set. IEHMOVE does not take exits to a user's label processing routines. 

Note: If a data set that has only user trailer labels is to be moved from a tape 
volume to a direct access volume, space must be previously allocated on the 
direct access volume to ensure that a track is reserved to receive the user labels. 

Note: To understand how, where, and why data sets are cataloged under VS2, see 
OS/VS Virtual Storage Access Method (VSAM) Programmer's Guide, GC26-3818. 



Data sets with fixed or variable records can be reblocked to a different block size 
by previously allocating the desired block size on the receiving volume. No 
reblocking can be performed when loading or unloading. 

When moving or copying data sets with undefined record format and reblocking 
to a smaller block size (that is, transferring records to a device with a track 
capacity smaller than the track capacity of the original device), the user must 
make the block size for the receiving volume equal to or larger than the size of 
the largest record in the data set being moved or copied. 

Moving or Copying a Data Set 

IEHMOVE can be used to move or copy sequential, partitioned, and direct access 
data sets, as follows: 

• A sequential data set can be: (1) moved from one direct access or non-direct 
access volume to another (or to the same volume provided that it is a direct 
access volume), or (2) copied from one direct access or non-direct access 
volume to another (or to the same volume provided that the data set name is 
changed and the receiving volume is a direct access volume). 

• A direct access data set can be moved or copied from one direct access 
volume to another provided that the receiving device type is the same device 
type or a larger device type and that the record size does not exceed 32K. 
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• A partitioned data set can be: (1) moved from one direct access volume to 
another (or to the same volume) or, (2) copied from one direct access volume 
to another (or to the same volume provided that the data set name is 
changed). 

Note: When iehmove uncatalogs a data set which has one or more aliases, the 
aliases are also removed. An alias can be replaced by means of the Access 
Method Services program when the data set is cataloged later. If an alias name is 
specified in the dsname or pds keyword, the true name only is moved or 
copied. Cataloging is done with the true name. The alias is removed if any 
uncataloging is done. 

In addition, IEHMOVE can be used to move or copy multivolume data sets. To 
move or copy a multivolume data set, specify the complete volume list in the 
vol=SER parameter on the dd statement. To move or copy a data set that 
resides on more than one tape volume, specify the volume serial numbers of all 
the tape volumes and the sequence numbers of the data set on the tape volumes 
in a utility control statement. (You can specify the sequence number even if the 
data set to be moved or copied is the only data set on a volume.) To move or 
copy a data set to more than one tape volume, specify the volume serial numbers 
of all the receiving volumes in a utility control statement. 

A data set with the unmovable attribute can be moved or copied from one direct 
access volume to another or to the same volume provided that space has been 
previously allocated on the receiving volume. Change the name of a data set to 
move or copy it to the same volume, svclib can be moved or copied to another 
location on the system residence volume, provided that space is available and 
that space has been previously allocated on that volume. IEHPROGM must be 
used immediately after such a move operation to rename the moved version 
sysi. svclib. After such a copy operation, IEHPROGM must be used to scratch 
the old version and to rename the copied version. In either case, IEHIOSUP must 
be used immediately after the iehprogm step to update the new version of 
svclib. 

When moving or copying a bdam data set from one device to another device of 
the same type, relative track and relative block integrity are maintained. 

When moving or copying a bdam data set to a larger device, relative track 
integrity is maintained for data sets with variable or undefined record formats; 
relative block integrity is maintained for data sets with fixed record formats. 

When moving or copying a bdam data set to a smaller device or a tape, the data 
set is unloaded. An unloaded data set is loaded only when it is moved or copied 
to the same device type from which it was unloaded. 

Table 21-4 shows basic and optional move and copy operations for sequential, 
and partitioned data sets. 
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Table 21-4. Moving and Copying Sequential and Partitioned Data Sets 



Operation Basic Actions 



Move 
Sequential 



Move 
Partitioned 



Move the data set. For direct access, 
scratch the source data. For cataloged 
data sets, update the catalog 
to refer to the moved data set. 

Move the data set. For direct access, 
scratch the source data. For cataloged 
data sets, update the catalog to refer 
to the moved data set. 



Copy 
Sequential 



Copy 
Partitioned 



Copy the data set. The source data set 
is not scratched. The catalog is not 
updated to refer to the copied data set. 

Copy the data set. The source data is 
not scratched. The catalog is not 
updated to refer to the copied data 
set. 



Optional Actions 

Prevent automatic cataloging of the 
moved data set. Rename the moved 
data set. 



Prevent automatic cataloging of the 
moved data set. Rename the moved 
data set. Re-allocate directory space. 
(Not possible if the space was not 
allocated by IEHMOVE during this 
move function.) Perform a merge 
operation using members from two or 
more data sets. Move only selected 
members. Replace members. Unload 
the data set. 

Uncatalog the source data set. Catalog 
the copied data set. Rename the 
copied data set. 

Uncatalog the source data set. Catalog 
the copied data set. Rename the 
copied data set. Re-allocate 
directory space. (Not possible if 
the space previously allocated is 
partially used.) Perform a merge 
operation using members from two 
or more data sets. Copy only 
selected members. Replace members. 
Unload the data set. 



IEHMOVE moves or copies partitioned members in the order in which they appear 
in the partitioned directory. That is, moved or copied members are placed in 
collating sequence on the receiving volume. 

Figure 21-1 shows a copied partitioned data set. Note that the members are 
copied in the order in which they appear in the partitioned directory. IEBCOPY 
can be used to copy data sets whose members are not to be collated. 



Source data set 



Copied data set 




Figure 21-1. Partitioned Data Set Before and After an iehmove Copy Operation 

Members that are merged into an existing data set are placed, in collating 
sequence, after the last member in the existing data set. 

Figure 21-2 shows members from one data set merged into an existing data set. 
Note that members A, C, and G from the existing data set are copied to the 
receiving volume before members B and F are copied from the source data set. 
Members B and F are copied in collating sequence. 
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Source data set 



Existing data set 
prior to merge 



Directory 



Members 




Existing data set 
after merge 




Figure 21-2. Merging Two Data Sets Using iehmove 

Figure 21-3 shows how members from two data sets are merged into an existing 
data set. Members from additional data sets can be merged in a like manner. 
Note that members A, C, and G are copied from the existing data set before any 
members are copied from the source data sets. Members F, B, D, and E from the 
source data sets are copied in collating sequence. 



Source data sets 



Existing data set 
prior to merge 



Existing data set 
after merge 





Note: New members 
are placed in 
collating sequence 
after existing 
members 

Figure 21-3. Merging Three Data Sets Using iehmove 

Moving or Copying a Volume of Data Sets 

IEHMOVE can be used to move or copy the data sets of an entire direct access 
volume to another volume or volumes. A move operation differs from a copy 
operation in that the move operation scratches source data sets, while the copy 
operation does not. For both operations, any cataloged entries associated with 
the source data sets remain unchanged. IEHPROGM can be used to uncatalog all 
of the cataloged data sets and recatalog them according to their new location. 
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If a volume of data sets is moved or copied to tape, the data sets must be 
retrieved one by one by data set name and file-sequence number, or by 
file-sequence number for unlabeled or non-standard labeled tapes. 

Note: IEHMOVE ignores VSAM, ISAM, and SYSCTLG data sets. 

The move-volume feature does not merge partitioned data sets. If a data set on 
the volume to be moved or copied has a name identical to a data set name on 
the receiving volume, the data set is not moved, copied, or merged onto the 
receiving volume. 

Table 21-5 shows basic and optional move and copy operations for a volume of 
data sets. 

Table 21-5. Moving and Copying a Volume of Data Sets 

Operation Basic Actions Optional Actions 

Move a volume Move all data sets not protected by a Include password-protected data 

of data sets password to the specified direct access sets in the operation. Move to a 

volumes. Scratch the source data sets tape volume. 

for direct access volumes. The catalog 

is not updated. 

COPY a volume Copy all data sets not protected by a Include password-protected data 

of data sets password to the specified direct access sets in the operation. Catalog all 

volume. The source data sets are not copied data sets. Copy to a tape 

scratched. volume. 

Moving or Copying Direct Data Sets with Variable Spanned Records 

IEHMOVE can be used to move or copy direct data sets with variable spanned 
records from one direct access volume to a compatible direct access volume, 
provided that the record size does not exceed 32K. 

Because a direct access data set can reside on one to five volumes (all of which 
must be mounted during any move or copy operation), it is possible for the data 
set to span volumes. However, single variable spanned records are contained on 
one volume. 

Relative track integrity is preserved in a move or copy operation for spanned 
records. Moved or copied direct access data sets occupy the same relative 
number of tracks that they occupied on the source device. 

If a direct data set is unloaded (moved or copied to a smaller device or tape), it 
must be loaded back to the same device type from which it was originally 
unloaded. 

When moving or copying variable spanned records to a larger device, record 
segments are combined and re-spanned if necessary. Because the remaining track 
space is available for new records, variable spanned records are unloaded before 
being moved or copied back to a smaller device. 

If a user wishes to create a direct data set without using data management BDAM 
macros, all data management specifications must be followed. Special attention 
must be given to data management specifications for RO track capacity record 
content, segment descriptor words, and the BFTEK=R parameter. 

When moving or copying a multivolume data set, the secondary allocation for 
direct data sets should be at least two tracks. (See the "WRITE SZ" macro in 
OS/VS Data Management Macro Instructions, GC26-3793.) 
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Input and Output 

IEHMOVE uses the following input: 



• One or more data sets, which contain the data to be moved, copied, or merged 
into an output data set. 

• A control data set, which contains utility control statements that are used to 
control the functions of the program. 

• A work data set, which is a work area used by IEHMOVE. 
IEHMOVE produces the following output: 

• An output data set, which is the result of the move, copy, or merge operation. 

• A message data set, which contains informational messages (for example, the 
names of moved or copied data sets) and error messages, if applicable. 

IEHMOVE produces a return code to indicate the results of program execution. 
The return codes and their meanings are: 

• 00, which indicates successful completion. 

• 04, which indicates that a specified function was not completely successful. 
Processing continues. 

• 08, which indicates a condition from which recovery is possible. Processing 
continues. 

• 12, which indicates an unrecoverable error. The job step is terminated. 

• 16, which indicates that is is impossible to OPEN the SYSIN or SYSPRINT data 
set. 



Control 



IEHMOVE is controlled by job control statements and utility control statements. 
The job control statements are used to execute or invoke the program, define the 
devices and volumes used and produced by IEHMOVE, and prevent data sets from 
being deleted inadvertently. 

Utility control statements are used to control the functions of the program and to 
define those data sets or volumes that are to be used. 

Job Control Statements 

Table 21-6 shows the job control statements necessary for using IEHMOVE. 
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Table 21-6. iehmove Job Control Statements 

Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (PGM-IEHMOVE) or, if the job control statements 

reside in a procedure library, the procedure name. This statement can include 
optional PARM information; see "PARM Information on the EXEC Statement" 
below. 

SYSPRINT DD Defines a sequential message data set. The data set can be written onto a 
system output device, a magnetic tape volume, or a direct access volume. 

SYSUT1 DD Defines a volume on which 3 work data sets required by IEHMOVE are placed. 

anynamel DD Defines a permanently mounted volume. (The system residence volume is 
considered to be a permanently mounted volume.) 

anyname2 DD Defines a mountable device type. 

tape DD Defines a tape volume to be used when moving or copying from or to a 7-track 

tape volume, a 9-track tape volume not having standard labels, or a 1600 bits 
per inch, 9-track tape volume on a single density unit, or when copying to an 
800 bits per inch tape on a dual density unit. 

SYSIN DD Defines the control data set. The data set, which contains utility control 
statements, usually follows the job control statements in the input stream; 
however, it can be defined either as an unblocked sequential data set or as a 
member of a procedure library. 

The SYSUTl DD statement can be coded: 

//SYSUTl DD UNIT=xxxx,VOLUME==SER=xxxxxx,DISP=OLD 

At least 3 utility work areas of 13, 13, and 26 contiguous tracks, respectively, 
must be available for work space on the volume defined by the SYSUTl DD 
statement. (This figure is based on a 2314 being the work volume. If a direct 
access device other than a 2314 is used, an equivalent amount of space must be 
available.) 

The anynamel DD statement can be coded: 

//anynamel DD UNIT=xxxx,VOLUME=SER=xxxxxx,DISP=OLD 

In the anynamel DD statement, the UNIT and VOLUME parameters define the 
device type and volume serial number. The DlSP=OLD specification prevents the 
inadvertent deletion of a data set. The anynamel DD statement is arbitrarily 
assigned the ddname ddi in the iehmove examples. 

The anyname2 DD statement can be coded: 

//anyname2 DD UNIT=xxxx,VOLUME=SER=xxxxxx,DISP=OLD 

When the number of volumes to be processed is greater than the number of 
devices defined by DD statements, there must be an indication (in the applicable 
DD statements) that multiple volumes are to be processed. This indication can be 
in the form of deferred mounting, as follows: 

//anyname2 DD UNIT=(xxxx„DEFER),VOLUME=(PRIVATE,...), 
// DISP=(...,KEEP) 

See "Appendix C: DD Statements for Defining Mountable Devices" for 
information on defining mountable devices. The anyname2 DD statement is 
arbitrarily assigned the ddname DD2 in the IEHMOVE examples. DD statements 
defining additional mountable device types are assigned names DD3, DD4, etc. 

The tape DD statement can be coded: 

//tape DD DSNAME=xxxxxxxx,UNIT=xxxx,VOLUME=SER=xxxxxx, 
// DISP=(...,KEEP),LABEL=(...,...),DCB=(TRTCH=C,DEN=x) 

when 7-track tape is to be used. A utility control statement parameter refers to 
the tape DD statement for label and mode information. 
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Restrictions 



The date on which a data set is moved or copied to a magnetic tape volume is 
automatically recorded in the HDRl record of a standard tape label if a TODD 
parameter is specified in a utility control statement. An expiration date can be 
specified by including the EXPDT or RETPD subparameters of the LABEL 
keyword in the DD statement referred to by a TODD parameter. 

To define a sequence number for a data set on a tape volume, or to specify a 
specific device (for example, unit address 190), you must use a utility control 
statement instead of a DD statement. To move or copy a data set from or to a 
tape volume containing more than one data set, specify the sequence number of 
the data set in a utility control statement. To move or copy a data set from or to 
a specific device, specify the unit address (rather than a group name or device: 
type) in a utility control statement. To copy to a unit record or unlabeled tape 
volume, specify any standard name or number in a utility control statement. 

IEHMOVE automatically calculates and allocates the amount of space needed for 
the work areas. No SPACE parameter, therefore, should be coded in the SYSUTl 
DD statement. If, in the EXEC statement, POWER=3 is specified, the work space 
requirement is three times the basic requirements, etc. 

With the exception of the SYSIN and SYSPRINT DD statements, all DD statements 
shown in Table 21-6 are used as device allocation statements, rather than as true 
data definition statements. Because IEHMOVE modifies the internal control blocks 
created by device allocation DD statements, these statements must not include 
the DSNAME parameter. (All data sets are defined explicitly or implicitly by 
utility control statements.) 

A merge operation requires that one DD statement defining a mountable device 
be present for each source volume containing data to be included in the merge 
operation. 

Prior space allocations can be made by specifying a dummy execution of 
IEHPROGM before the execution of IEHMOVE. 

Blocked format data sets that do not contain user data TTRNs or keys can be 
reblocked or unblocked by including the proper keyword subparameters in the 
DCB operand of the DD statement used to previously allocate space for the data 
set. The new blocking factor must be a multiple of the logical record length 
originally assigned to the data set. (For a discussion of user data TTRNs, refer to 
OS/VS Data Management Services Guide, GC26-3783.) 



The block size for the SYSPRINT data set must be a multiple of 121. The 
block size for the SYSIN data set must be a multiple of 80. Any blocking 
factor can be specified for these block sizes. 

One anynamel DD statement must be included for each permanently mounted 
volume referred to in the job step. 

One anyname2 DD statement must be included for each mountable device to 
be used in the job step. 

When IEHMOVE is dynamically invoked in a job step containing another 
program, the DD statements defining mountable devices for IEHMOVE must be 
included in the job stream prior to DD statements defining data sets required 
by the other program. 
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PARM Information on the EXEC Statement 

The EXEC statement for IEHMOVE can contain PARM information that is used by 
the program to allocate additional work space and/or control line density on 
output listings. The EXEC statement can be coded, as follows: 

// EXEC PGM=IEHMOVE[,PARM= {'POWER=n'} 

{'POWER=n,LINECNT=xx'} 
{'LINECNT=xx'}] 

The POWER=n parameter is used to request that the normal amount of space 
allocated for work areas be increased n times. The POWER parameter is used 
when 750 or more members are being moved or copied. The progression for the 
value of n is: 

• POWER=2 when 750 to 1,500 members are to be moved or copied. 

• POWER=3 when 1,501 to 2,250 members are to be moved or copied. 

• POWER==4 when 2,251 to 3,000 members are to be moved or copied. 

If POWER==2, the work space requirement on the SYSUTl volume is two times the 
basic requirement; if POWER=3, work space requirement is three times the basic 
requirement, etc. For example, if POWER=2, three areas of 26, 26, and 52 
contiguous tracks on a 2314 must be available. 

Job Control Language for the Track Overflow Feature 

A data set containing track overflow records can be moved or copied if the 
source volume and the receiving volume are mounted on direct access devices 
that support the track overflow feature. (For BDAM data sets, the source and 
receiving devices must be the same device type.) 

A data set that was written without track overflow can be moved or copied with 
or without track overflow or vice versa if the following conditions are met: 

• Space was allocated for the data set prior to the request for a move or copy 
operation. 

• The DD statement used for that allocation included the subparameter to 
specify the changed track overflow value and all other desired values. (The 
RECFM specifications assigned when the data set was originally created are 
overridden by the RECFM subparameter in this DD statement.) 

If space has not been allocated, or if RECFM was not specified when space was 
allocated, the data set is moved or copied in accordance with RECFM 
specifications that were made when the data set was originally created. 

The track overflow attribute is not retained for a sequential data set that is 
moved or copied to a device other than a direct access device. 

Utility Control Statements 

IEHMOVE is controlled by the following utility control statements: 

• MOVE DSNAME statement, which is used to move a data set. 

• COPY DSNAME statement, which is used to copy a data set. 

• MOVE PDS statement, which is used to move a partitioned data set. 

• COPY PDS statement, which is used to copy a partitioned data set. 

• MOVE VOLUME statement, which is used to move a volume of data sets. 

• COPY VOLUME statement, which is used to copy a volume of data sets. 
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In addition, there are subordinate control statements that can be used to modify 
the effect of a MOVE PDS or COPY PDS operation. The subordinate control 
statements are: 

• INCLUDE statement, which is used to enlarge the scope of a MOVE PDS or 
COPY PDS statement by including a member or data set not explicitly included 
by the statement it modifies. 

• exclude statement, which is used with a MOVE PDS or COPY PDS statement 
to exclude data from the move or copy operation. 

• REPLACE statement, which is used with a MOVE PDS or COPY PDS statement 
to exclude a member from a move or copy operation and to replace it with a 
member from another partitioned data set. 

• SELECT statement, which is used with MOVE PDS or COPY PDS statements to 
select members to be moved or copied and, optionally, to rename the specified 
members. 

Notes: FROMDD must be specified in the control statement when no data set label 
information is available. TODD must be specified in the control statement when 
an expiration date (expdt) or retention period (retpd) is to be created or 
changed. 



MOVE DSNAME Statement 



The MOVE DSNAME statement is used to move a data set, other than ISAM, 
SYSCTLG or VSAM data sets or data spaces. The source data set is scratched. 

The format of the MOVE DSNAME statement is: 

[label] MOVE DSNAME= name 
,TO=dew'ce=//st 
[,FROM=dew'ce=//'st] 
[,UNCATLG] 

[,RENAME=name] 

[,FROMDD=ddname] 

[,TODD=ddname] 

where: 

DSNAME= name 

specifies the fully qualified name of the data set to be moved. 

TO=dev/ce=//st 

specifies the volume or volumes to which the data set is to be moved. 

FROM=dew'ce=//st 

specifies the volume or volumes on which the data set currently resides, if it is 
not cataloged. If the data set is cataloged and FROM is specified, the catalog is 
not updated. 

UNCATLG 

specifies that the catalog entry pertaining to the data set is to be removed. 
This parameter should be used only if the source data set is cataloged. 
UNCATLG is ignored if the volume is identified by FROM. 

RENAME= name 

specifies that the data set is to be renamed, and indicates the new name. 

FROMDD=ddname 

specifies the name of a DD statement from which DCB and LABEL information 
are obtained. This parameter is valid for data sets residing on magnetic tape 
volumes. 
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COPY DSNAME Statement 



TODD=ddname 

specifies the name of a DD statement from which DCB and LABEL information 
are obtained. This parameter, which is valid for data sets to be moved to tape 
volumes, describes the mode and label of the volume where the moved data 
set is to reside. RECFM, LRECL, and BLKSIZE information is ignored. 

If the data set is cataloged, the catalog is automatically updated unless UNCATLG 
is specified. 

The FROMDD and TODD parameters can be omitted for 800 bits per inch, 9-track 
tape with standard labels on single density units or for 1600 bits per inch, 
9-track tape with standard labels on dual density units. 



The COPY DSNAME statement is used to copy a data set, other than ISAM, 
SYSCTLG, or VSAM data sets or data spaces. 

The format of the COPY DSNAME statement is: 

[label] COPY DSNAME=name 
,TO=dev/ce=//st 
[,FROM=dew'ce= list] 
[,UNCATLG] 
[,CATLG] 
[,RENAME= name] 
[,FROMDD =ddname] 
[,TODD=ddname] 

where: 

DSNAME=name 

specifies the fully qualified name of the data set to be copied. 

TO=dewce==//st 

specifies the volume or volumes on which the data set is to be copied. 

FROM=dev/ce=//sf 

specifies the volume or volumes on which the data set currently resides, if it is 
not cataloged. 

UNCATLG 

specifies that the catalog entry pertaining to the source data set is to be 
removed. This parameter should be used only if the source data set is 
cataloged. UNCATLG is ignored if the volume is identified by FROM. 

CATLG 

specifies that the copied data set is to be cataloged. 

RENAME=name 

specifies that the data set is to be renamed, and indicates the new name. 

FROMDD=ddname 

specifies the name of the DD statement from which DCB and LABEL 
information are obtained. DCB attributes for unloaded data sets are always 
RECFM=FB, LRECL=80, and BLKSIZE=800. This parameter is valid for data sets 
residing on tape volumes. 

TODD=ddname 

specifies the name of a DD statement from which DCB and LABEL information 
are obtained. This parameter, which is valid for data sets to be copied to 
magnetic tape volumes, describes the mode and label of the magnetic tape 
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MOVE PDS Statement 



where the copied data set is to reside. RECFM, i..rf:cj ?M7F 

information is ignored. 

Note: The source data set, if cataloged, remains c « ; ^ 

specified. 

The FROMDD and TODD parameters can be omitted :or v}i b -!s p-: m n, 9 track 
tape with standard labels on single density units or for 1600 bits per inch, 
9-track tape with standard labels on dual density units. 



The MOVE PDS statement is used to move partitioned dais sei.s. When used in 
conjunction with INCLUDE, EXCLUDE, REPLACE, or riHCT statements, the 
MOVE PDS statement can be used to merge selected members of several 
partitioned data sets or to delete members. 

If IEHMOVE is used to allocate space for an output partitioned data set, the 
MOVE PDS statement can be used to expand a partitioned directory. 

If the receiving volume contains a partitioned data set with the same name, the 
two data sets are merged. The source data set is scratched. 

The format of the MOVE PDS statement is: 

[label] MOVE PDS= name 

,TO = device = serial 

[,FROM = device = serial] 

[,EXPAND=nn] 

[,UNCATLG] 

[,RENAME=name] 

[,FROMDD=ddname] 

[,TODD=ddname] 

where: 

PDS=name 

specifies the fully qualified name of the partiiio m d 

TO = device = serial 

specifies the device type and volume serial number of the volume to which the 
partitioned data set is to be moved. The list parameter may be used when 
unloading a partitioned data set that must span tape volumes. 

FROM = device = serial 

specifies the device type and volume serial number of the volume on which the 
partitioned data set currently resides, if it is not cataloged. If the data set is 
cataloged, FROM should not be written. FROM=d( \ * - - ' i-i; v bf i«sed when 
loading a PDS. 

EXPAND=nn 

specifies the number of 256-byte records (up to 99 decimal) to be added to 
the directory of the specified partitioned data set. expand will be ignored if 
space is previously allocated. 

UNCATLG 

specifies that the catalog entry pertaining to the source partitioned data set is 
to be removed. This parameter should be used only if the i urtt data set is 
cataloged. If the volume is identified by FROM, uncatl^; i- ignored. 

RENAME=name 

specifies that the data set is to be renamed, and indicates the new name. 
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COPY PDS Statement 



FROMDD=ddname 

specifies the name of a DD statement from which DCB and LABEL information 
are obtained. This parameter, which is valid for unloaded partitioned data sets 
on tape volumes, describes the mode and label of the magnetic tape and, in 
addition, must include the DCB attributes of the unloaded data set 
(RECFM=FB,LRECL=80,BLKSIZE=800). 

TODD=ddname 

specifies the name of a DD statement from which DCB and LABEL information 
are obtained. This parameter, which is valid for partitioned data sets to be 
unloaded to tape volumes, describes the mode and label of the magnetic tape 
on which the unloaded data set is to reside and, in addition, must include the 
DCB attributes of the unloaded data set (recfm=fb,lrecl=80,blksize=800). 

The FROMDD and TODD, parameters can be omitted for 800 bits per inch, 9-track 
tapes with standard labels on single density units or for 1600 bits per inch, 
9-track tape with standard labels on dual density units. 

Note: MOVE PDS causes the specified catalog to be updated automatically unless 
UNCATLG is specified. 



The COPY PDS statement is used to copy partitioned data sets. When used in 
conjunction with INCLUDE, EXCLUDE, REPLACE, or SELECT statements, the 
COPY PDS statement can be used to merge selected members of several 
partitioned data sets or to delete members. 

If IEHMOVE is used to allocate space for an output partitioned data set, the COPY 
PDS statement can be used to expand a partitioned directory. 

If the receiving volume already contains a partitioned data set with the same 
name, the two are merged. 

The format of the COPY PDS statement is: 



[label] COPY 



PDS=name 

,TO =dewce= serial 

[,FROM = device = serial] 

[,EXPAND=nn] 

[,UNCATLG] 

[,CATLG] 

[,RENAME= name] 

[,FROMDD =ddname] 

[,TODD =ddname] 



where: 



PDS= name 

specifies the fully qualified name of the partitioned data set to be copied. 

TO = device = serial 

specifies the device type and volume serial number of the volume to which the 
partitioned data set is to be moved. The list value may be used when 
unloading a partitioned data set that must span tape volumes. 

¥ROM=device= serial 

specifies the device type and volume serial number of the volume on which the 
partitioned data set currently resides, if it is not cataloged. If the data set is 
cataloged, FROM should not be written. FROM = device = list may be used when 
loading a PDS. 
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MOVE VOLUME Statement 



EXPAND=nn 

specifies the number of 256-byte records (up to 99 decimal) to be added to 
the directory of the specified partitioned data set. EXPAND cannot be specified 
if space is previously allocated. 

UNCATLG 

specifies that the catalog entry pertaining to the source partitioned data set is 
to be removed. This parameter should be used only if the source partitioned 
data set is cataloged. UNCATLG is ignored if the volume is identified by FROM. 

CATLG 

specifies that the copied partitioned data set is to be cataloged. 

RENAME= name 

specifies that the data set is to be renamed, and indicates the new name. 

FROMDD=ddname 

specifies the name of a DD statement from which DCB and LABEL information 
are obtained. This parameter, which is valid for unloaded partitioned data sets 
residing on magnetic tape volumes, describes the mode and label of the 
magnetic tape and, in addition, must include the DCB attributes of the 
unloaded data set (RECFM=FB,LRECL=80,BLKSIZE=800). 

TODD =ddname 

specifies the name of a DD statement from which DCB and LABEL information 
are obtained. This parameter, which is valid for partitioned data sets to be 
unloaded to magnetic tape volumes, describes the mode and label of the 
magnetic tape on which the unloaded data set is to reside and, in addition, 
must include the DCB attributes of the unloaded data set 

(RECFM=FB,LRECL=80,BLKSIZE=800). 

The FROMDD and TODD parameters can be omitted for 800 bits per inch, 9-track 
tapes with standard labels on single density units or for 1600 bits per inch, 
9-track tape with standard labels on dual density units. 

Note: The source partitioned data set remains cataloged unless UNCATLG is 
specified. 



The MOVE VOLUME statement is used to move all the data sets residing on a 
specified volume. Catalog entries associated with the data sets remain unchanged. 
Data sets to be moved must reside on direct access volumes. 

The format of the MOVE VOLUME statement is: 

[label] MOVE VOLUME=deWce= serial 
,TO=device=list 
[,PASSWORD] 

[,TODD=ddname] 

where: 

VOLUME=device=seria/ 

specifies the device type and volume serial number of the source volume. 

TO=dew'ce=//sf 

specifies the volume or volumes to which the data sets are to be moved. 

PASSWORD 

specifies that password protected data sets are to be included in the operation. 
If PASSWORD is omitted, only data sets that are not protected are moved. 
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COPY VOLUME Statement 



INCLUDE Statement 



TODD=ddname 

specifies the name of a DD statement from which DCB and label information 
are obtained. This parameter, which is valid for data sets to be moved to tape 
volumes, describes the mode and label of the receiving tape volume. TODD can 
be omitted for 800 bits per inch, 9-track tapes with standard labels on single 
density units or for 1600 bits per inch, 9-track tape with standard labels on 
dual density units. 



The COPY VOLUME statement is used to copy all the data sets residing on a 
specified volume. Catalog entries associated with the data sets remain unchanged. 
Data sets to be copied must reside on direct access volumes. 

The format of the COPY volume statement is: 



[label] COPY 



VOLUME=deWce=ser/a/ 
,TO = device = list 
[.PASSWORD] 
[,CATLG] 

[,TODD=ddname] 



where: 



VOLUME=dewce= serial 

specifies the device type and volume serial number of the source volume. 

TO=dewce=//st 

specifies the volume or volumes to which the data sets are to be copied. 

PASSWORD 

specifies that password protected data sets are to be included in the operation. 
If PASSWORD is omitted, only data sets that are not protected are copied. 

CATLG 

specifies that all copied data sets are to be cataloged. 

TODD=ddname 

specifies the name of a DD statement from which DCB and LABEL information 
are obtained. This parameter, which is valid for data sets to be copied to 
magnetic tape volumes, describes the mode and label of the receiving magnetic 
tape volume, todd can be omitted for 800 bits per inch, 9-track tapes with 
standard labels on single density units or for 1600 bits per inch, 9-track tape 
with standard labels on dual density units. 



The INCLUDE statement is used to enlarge the scope of MOVE PDS or COPY PDS 
statements by including a member or a data set not explicitly defined in those 
statements. The include statement follows the MOVE or COPY statement whose 
function it: modifies. Any number of INCLUDE statements can modify a MOVE or 
COPY statement. For a PDS, the INCLUDE statement is invalid when data is 
unloaded or when unloaded data is moved or copied. 

The format of the INCLUDE statement is: 



[label] INCLUDE 



DSNAME= name 
[.MEMBER = membername] 
[,FROM=dev/ce=//st] 
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EXCLUDE Statement 



SELECT Statement 



where: 

DSNAME=name 

specifies the fully qualified name of a data set. When the include statement 
modifies a MOVE PDS or COPY pds statement, either the entire named 
partitioned data set or a member of the data set is included in the operation. 

MEMBER = membername 

specifies the name of a member of the partitioned data set named in the 
DSNAME parameter. This member is merged with the partitioned data set that 
is moved or copied. Its record characteristics must be compatible with those of 
the data set with which it is being merged. The data set containing this 
member is not scratched, regardless of the operation. This parameter is valid 
and required only when the include statement modifies a move pds or 
COPY pds statement. 

FROM=deWce=//"st 

specifies the volume or volumes on which the data set resides, if the data set is 
not cataloged. If the data set is cataloged, from should not be specified. If 
FROM is omitted, the specified data set is assumed to be cataloged. 



The EXCLUDE statement is used to restrict the scope of MOVE PDS, or COPY pds 
statements by excluding a specific portion of data defined in those statements. 

Partitioned data set members excluded from a move pds operation cannot be 
recovered (the source data set is scratched). Any number of exclude 
statements can modify a MOVE pds or COPY pds statement. 

The format of the EXCLUDE statement is: 

[label] EXCLUDE MEMBER= membername 

where: 

MEMBER= membername 

identifies a member to be excluded from the partitioned data set being moved 
or copied when the EXCLUDE statement modifies a MOVE PDS or COPY PDS 
statement. 



The SELECT statement is used with the move pds or COPY PDS statement to 
select members to be moved or copied, and to optionally rename these members. 
The SELECT statement cannot be used with either the exclude or REPLACE 
statement to modify the same MOVE pds or COPY pds statement. The select 
statement is invalid when data is unloaded or when unloaded data is moved or 
copied. 

The format of the SELECT statement is: 



[label] SELECT 



{ MEMBER = (nameUname. . .) } 

{ MEMBER = ((name,newname)[,(name,newname)] . 



•)} 



where: 



MEMBER= (name[,name]. . .) 

identifies the members to be moved or copied. These members belong to the 
partitioned data set identified in the preceding move pds or COPY pds 
statement. 

MEMBER=((name,newname)[,(name,newname)]...) 

identifies the members to be moved or copied and gives the new name for 
each member. 



IEHMOVE Program for VS2 Release 2 21-19 



REPLACE Statement 



IEHMOVE Examples 



The REPLACE statement is used with a MOVE PDS or COPY PDS statement to 
exclude a member from the operation and replace it with a member from another 
partitioned data set. The new member must have the same name as the old 
member and must possess compatible record characteristics. Any number of 
REPLACE statements can modify a MOVE PDS or COPY PDS statement. The 
REPLACE statement is invalid when data is unloaded or when unloaded data is 
moved or copied. 

The format of the REPLACE statement is: 



[label] REPLACE 



DSNAME=name 
,MEMBER=name 
[,FROM = device = serial] 



where: 



DSNAME== name 

specifies the fully qualified name of the partitioned data set that contains the 
new member. 

MEMBER= name 

specifies the name of the member. 

FROM=device=serial 

specifies the device type and volume serial number of the volume that contains 
the partitioned data set named in the DSNAME parameter. If the partitioned 
data set is cataloged, FROM should not be specified. 

If FROM is not specified, the partitioned data set is assumed to be cataloged. 



The following examples illustrate some of the uses of IEHMOVE. Table 21-7 can 
be used as a quick reference guide to IEHMOVE examples. The numbers in the 
"Example" column point to the examples that follow. 
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Table 21-7. iehmove Example Directory 



Data Set 
Operation Organization 

MOVE Sequential 



COPY 

MOVE 

MOVE 
MOVE 

MOVE 

MOVE 

MOVE 

COPY 
COPY 



Sequential 

Partitioned 

Volume 
Partitioned 

Partitioned 

Sequential 

Sequential 

Sequential 
Partitioned 



Device Comments Example 

3330 Disk, Source volume is demounted after 
2314 Disks job completion. Two mountable 

disks. 1 

3330 Disk, Three cataloged sequential data 
2314 or sets are to be copied. The 2314 

2319 Disks 1 or 2319 are mountable. 2 

3330 Disk, A partitioned data set is to be 
2314 Disks moved; a member from another 

PDS is to be merged with it. 3 

3330 Disk, Volume of data sets is to be moved. 
2314 Disks 4 

3330 Disk, A data set is to be moved to a 
2314 Disks volume on which space was 

previously allocated. 5 

3330 Disk, Three data sets are to be moved 
2314 Disk and unloaded to a volume on which 

space was previously allocated. 6 

2314 Disk, A sequential data set is to be 
2400 Tape unloaded to an unlabeled 9-track 

tape volume. 7 

3330 Disk, Unloaded data sets are to be 
2314 Disk, loaded from a single volume. 
2400 Tape 8 

2314 Disk, Data sets are to be copied from 

2400 Tape separate source volumes. 9 

2400 Tape, Unloaded data sets are to be 
2314 Disks loaded from unlabeled tape to a 

specific device. 10 



1 Note that the 2319 disk is functionally equivalent to the 2314 disk; to use the 2319, specify 
2314 in the control statement. 



IEHMOVE Example 1 



In this example, three data sets (SEQSETl, SEQSET2, and SEQSET3) are to be 
moved from a disk volume to three separate disk volumes. Each of the three 
receiving volumes is mounted when it is required by IEHMOVE. The source data 
sets are not cataloged. Space is allocated by IEHMOVE. 

The example follows: 



//MOVEDS 

// 

//SYSPRINT DD 
//SYSUT1 DD 

//DD1 DD 

//DD2 DD 



JOB 09#550, GREEN 
EXEC PGM= IEHMOVE 
SYSOUT=A 

UNIT=3330,VOLUME=SER=333000,DISP=OLD 
UNIT=2314,VOLUME=SER=1 11111 ,DISP=OLD 
UNIT=( 2314, , DEFER ),DISP=OLD, 
// VOLUME=( PRIVATE , , SER=( 231400)) 

//DD3 DD VOLUME= (PRIVATE, RETAIN, SER=( 23141 1 ) ), 

// UNIT=2314,DISP=OLD 
//SYSIN DD * 

MOVE 
MOVE 
MOVE 
/* 



DSNAME=SEQSET1 , TO=23 14=231 400 ,FROM=231 4=23 141 1 
DSNAME=SEQSET2 , TO=23 1 4=23 1 412, FROM=23 1 4=23 1411 
DSNAME=SEQSET3 , TO=2 3 14=231413, FROM=2 3 14=231411 
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IEHMOVE Example 2 



IEHMOVE Example 3 



The control statements are discussed below: 

• SYSUTl DD defines the device that is to contain the work data set. 

• DDi DD defines the system residence device. 

• DD2 DD defines the mountable device on which the receiving volumes will be 
mounted as they are required. 

• DD3 DD defines a mountable device on which the source volume is to be 
mounted. Because the RETAIN subparameter is included, the volume remains 
mounted until the job has completed. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• MOVE moves the source data sets to volumes 231400, 231412, and 231413, 
respectively. The source data sets are scratched. 



In this example, three cataloged data sets are to be copied to a 2314 or 2319 
volume. Note that the 2319 is functionally equivalent to the 2314; to use a 2319, 
specify 2314 in the control statement. Space is allocated by IEHMOVE. The 
catalog is not updated. The source data sets are not scratched. 



The example follows: 



//COPYPDS JOB 


// 


EXEC 


//SYSPRINT DD 


//SYSUT1 


DD 


//DD1 


DD 


//DD2 


DD 


//DD3 


DD 


//SYSIN 


DD 




COPY 




COPY 




COPY 



/* 



09#550, GREEN 

PGM= IEHMOVE 

SYSOUT=A 

UNIT=23 1 4 , VOLUME=SER=23 1 400 , DISP==OLD 

UNIT=3330,VOLUME=SER=1 11111 ,DISP=OLD 

UNIT=23 1 4 , VOLUME=SER=23 1 400 , DISP==OLD 

UNIT=23 1 4 , VOLUME=SER=23 1 401, DISP==OLD 

* 

DSNAME=SEQSET1 ,TO=23 14=231 401 
DSNAME=SEQSET3 , TO=23 1 4=23 1 40 1 
DSNAME=SEQSET4 , TO=23 1 4=23 1 40 1 



The control statements are discussed below: 

• SYSUTl DD defines the device that is to contain the work data set. 

• DDI DD defines the system residence device. 

• DD2 DD defines a mountable device on which the source volume is mounted. 

• DD3 DD defines a mountable device on which the receiving volume is 
mounted. 

• SYSIN DD defines the control data set which follows in the input stream. 

• COPY copies the source data sets onto volume 231401. 

Note: This example implies that the cataloged source data sets all exist on a 2314 
volume. If the data sets existed on a volume or volumes other than a 2314, the 
necessary DD statements would have to be included in this example to define the 
applicable mountable device(s). 



In this example, a partitioned data set (PARSETl) is to be moved to a disk 
volume. In addition, a member (PARMEM3) from another partitioned data set 
(PARTSET2) is to be merged with the source members on the receiving volume. 
The source partitioned data set (PARTSETl) is scratched. Space is allocated by 

IEHMOVE. 
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IEHMOVE Example 4 



//SYSUT1 


DD 


//DD1 


DD 


//DD2 


DD 


//DD3 


DD 


//DD4 


DD 


//SYSIN 


DD 


MOVE 


P] 


INCLUDE 


d: 


/* 





The example follows: 

//MOVEPDS JOB 09#550, GREEN 

// EXEC PGM=IEHMOVE 

//SYSPRINT DD SYSOUT=A 

UNIT=3330,VOLUME=SER=333000,DISP=OLD 
UNIT=2314,VOLUME=SER=1 11111 ,DISP=OLD 
UNIT=23 1 4 , VOLUME=SER=23 1 400 , DISP=OLD 
UNIT=23 1 4 , VOLUME=SER=23 1 410, DISP=OLD 
UNIT=23 1 4 , VOLUME=SER=23 1 420 , DISP=OLD 
* 

PDS=PARTSET1 , TO=23 1 4=23 1 420 , FROM=23 1 4=23 1 400 
DSNAME=PARTSET2 , MEMBER=PARMEM3 , FROM=23 1 4=23 1410 

The control statements are discussed below: 

• SYSUTl DD defines the device that is to contain the work data set. 

• DDl DD defines the system residence device. 

• The DD2, DD3, and DD4 DD statements define mountable devices that are to 
contain the two source volumes and the receiving volume. 

• SYSIN dd defines the control data set, which follows in the input stream. 

• move defines the source partitioned data set, the volume that contains it, and 
its receiving volume. 

• INCLUDE includes a member from a second partitioned data set in the 
operation. 



In this example, a volume of data sets is to be moved to a 2314 volume. All data 
sets that are successfully moved are scratched from the source volume; however, 
any catalog entries pertaining to those data sets are not changed. Space is 
allocated by IEHMOVE. The work data set is deleted when the job step is 
completed. 

The example follows: 

//MOVEVOL JOB 09#550, GREEN 

// EXEC PGM= IEHMOVE 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD UNIT=2314,VOLUME=SER=231400,DISP=OLD 

//DD1 DD UNIT=3330,VOLUME=SER=1 1 1 1 1 1 ,DISP=OLD 

//DD2 DD UNIT=2314,VOLUME=SER=231400,DISP=OLD 

//DD3 DD UNIT=2314,VOLUME=SER=231401 ,DISP=OLD 

//SYSIN DD * 

MOVE VOLUME=23 14=23 1401 , TO=23 14=231 400 , PASSWORD 
/* 

The control statements are discussed below: 

• SYSUTl dd defines the device that is to contain the work data set. The work 
data set is removed from the receiving volume when the job step is completed. 

• DDl DD defines the system residence device. 

• DD2 DD defines the mountable device on which the receiving volume is to be 
mounted. 

• DD3 DD defines a mountable device on which the source volume is to be 
mounted. 

• SYSIN DD defines the control data set, which follows in the input stream. 
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• MOVE specifies a move operation for a volume of data sets and defines the 
source and receiving volumes. This statement also indicates that 
password-protected data sets are to be included in the operation. 

Note: IEHPROGM can be used to uncatalog catalog entries pertaining to 
non-VSAM source data sets and to catalog the moved versions of those data sets. 



In this example, a partitioned data set is to be moved to a 2314 volume on which 
space has been previously allocated for the data set. The source data set is 
scratched. The work data set is deleted when the job step is completed. 

The example follows: 

//ALLOCATE JOB 09# 550, GREEN 

// EXEC PGM= IEHPROGM 

//SYSPRINT DD SYSOUT=A 

//SET1 DD DSNAME=PDSSET1 , UNIT=23 1 4 ,DISP=( NEW, KEEP), 

// VOLUME=SER=231401,SPACE=(TRK,( 100, 10,10) ), 

// DCB=(RECFM=FB,LRECL=80,BLKSIZE=2000 ) 

//SYSIN DD * 

/* 

// EXEC PGM=IEHMOVE 



//SYSPRINT DD 



//SYSUT1 


DD 


//DD1 


DD 


//DD2 


DD 


//DD3 


DD 


//SYSIN 


DD 




MOVE 



/« 



SYSOUT=A 

UNIT=23 1 4 , VOLUME=SER=23 1401, DISP=OLD 

UNIT=3330,VOLUME=SER=1 11111 ,DISP=OLD 

UNIT=23 1 4 , VOLUME=SER=23 1401, DISP=OLD 

UNIT=23 1 4 , VOLUME=SER=23 1 402 , DISP=OLD 

* 

PDS=PDSSET1 ,TO=23 14=23 1401 , FROM=23 1 4=23 1402 



The IEHPROGM job step is used to allocate space for data set PDSSETl on a 
2314 volume. 

The control statements are discussed below: 

• SYSUTl DD defines the device that is to contain the work data set. The data 
set is removed from the receiving volume at the completion of the program. 

• ddi DD defines the system residence device. 

• DD2 DD defines the device on which the receiving volume is to be mounted. 

• DD3 DD defines a mountable device on which the source volume is to be 
mounted. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• MOVE specifies a move operation for the partitioned data set PDSSETl and 
defines the source and receiving volumes. 



In this example, three partitioned data sets are to be moved from three separate 
source volumes to a 2314 volume. The source data set PDSSET3 is unloaded. 
(The record size exceeds the track capacity of the receiving volume.) The work 
data set is deleted when the job step is completed. 
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The example follows: 

//ALLOCATE JOB 09#550, GREEN 

// EXEC PGM=IEHPROGM 

//SYSPRINT DD SYSOUT=A 

//SET1 DD DSNAME=PDSSET1 , UNIT=23 1 4, DISP=( NEW, KEEP ) , 

// VOLUME=SER=23 1401 , SPACE=( TRK, ( 50, 10, 5 ) ), 

// DCB=( REOFM=FB, LRECL=80,BLKSIZE=1600 ) 

//SET2 DD DSNAME=PDSSET2,UNIT=2314,DISP=(NEW,KEEP), 

// VOr,UME=SER=231401 , SPACE=( TRK, ( 25,5,5 ) ), 

// DCB--( RECFM=F, LRECL=80 , BLKSIZE=80 ) 

//SET3 DD DSNAME=PDSSET3,UNIT=2314,DISP=(NEW,KEEP), 

// VOLUME=SER=2 31401 ,SPAOE=( TRK, ( 25,5 ) ), 

// DCB=(RECFM=U,BLKS1ZE=50Q0 ) 



PGM- IEHMOVE 

SYS0UT=A 

UNTT=2 3 1 4 , VOLUME=SER=2 3 1401, DT SP=OLD 

UNIT=33 30 , VOLUME-SER- 111111, DTSP=OLD 

UNIT=( 2314, , DEFER ),DISP=OLD, 

VOLUME=( PRIVATE, ,SER=( 231400 ) ) 

UN r T=2 3 1 4 , VOLUME=SER=2 31401, DTSP=OLD 

* 

PDS=PDSSET1 ,TO=23 14=23 1401 , FPOM=23 1 4=23 1 400 
PDS=PDSSET2 , TO=23 1 4=2 3 1401, FROM=23 1 4=2 3 1 40 1 
PDS=PDSSET3 , TO=23 1 4=23 1 40 1 , FROM=23 1 4=23 1 402 



//SYSIN 
/* 


DD 


/ 
// 


EXEC 


//SYSPRINT DD 


//SYSUT1 


DD 


//DD1 


DD 


//DD2 


DD 


// 




//DD3 


DD 


//SYSIN 


DD 




MOVE 




MOVE 




MOVE 



/< 



The IEHPROGM job step is used to allocate space for the partitioned data sets 
PDSSETl, PDSSET2, and PDSSET3 on the receiving volume. The SPACE parameter 
in the SET3 DD statement allocates space for a sequential data set. This is 
necessary to successfully unload the partitioned data set PDSSET3. The dcb 
attributes of PDSSET3 are: 

DCB=(RECFM=U,BLKS1ZE=5000) 
The unloaded attributes are: 

DCB=(RECFM=FB,LRECL=80,BLKSIZE=800) 

The control statements are discussed below: 

• SYSUTi DD defines the device that is to contain the work data set. 

• DDi DD defines the system residence device. 

• DD2 DD defines a mountable device on which the source volumes are mounted 
as they are required. 

• DD3 DD defines a mountable device on which the receiving volume is 
mounted. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• MOVE specifies move operations for the partitioned data sets and defines the 
source and receiving volumes. 

Note: For a discussion on estimating space allocations, refer to OS/VS Data 
Management Services Guide, GC26-3783. 



In this example, a sequential data set is to be unloaded onto a 9-track, unlabeled 
tape volume (800 bits per inch). The work data set resides on the source volume 
and is deleted when the job step is completed. 
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The example follows: 

72 
//UNLOAD JOB 09 # 550, GREEN 
// EXEC PGM=IEHMOVE 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD UNIT=2314,VOLUME=SER=231400,DISP=OLD 
//DD 1 DD UNIT=23 1 4 , VOLUME=SER= 111111, DISP=OLD 
//DD2 DD UNIT=2314,VOLUME=SER=231400,DISP=OLD 
//TAPEOlTr DD UNIT=2400,VOLUME=SER=SCRTCH,DISP=OLD, 
// DCB=( DEN=2,RECFM=FB,LRECL=80,BLKSIZE=800 ) , 
// LABEL=( ,NL) 
//SYSIN DD * 

MOVE DSNAME=SEQSET1,TO=2400=SCRTCH, C 

FROM=23 1 4=23 1 400 , TODD=TAPEOUT 
/* 

The control statements are discussed below: 

• SYSUTl DD defines the device that is to contain the work data set. 

• DDl DD defines the system residence device. 

• DD2 DD defines a mountable device on which the source volume is mounted. 

• TAPEOUT DD defines a mountable device on which the receiving tape volume 
is mounted. This statement also provides label and mode information. 

• SYSIN DD defines the control data set which follows in the input stream. 

• move moves the sequential data set SEQSETl from a 2314 volume to the 
receiving tape volume. The data set is unloaded. The TODD parameter in this 
statement refers to the TAPEOUT DD statement for label and mode 
information. 



In this example, three unloaded sequential data sets are to be loaded from a 
labeled, 7-track tape volume (556 bits per inch) to a 2314 volume. Space is 
allocated by IEHMOVE. The example assumes that the 23.14 volume is capable of 
supporting the data sets in their original forms. 

The example follows: 

//LOAD JOB 09#550,GREEN 
// EXEC PGM=IEHMOVE 

//SYSPRINT DD SYSOUT=A 
//SYSUT1 DD 
//DD1 DD 
//DD2 DD 
//TAPESETS DD 



72 



UNIT=2 3 1 4 , VOLUME=SER= 
UNIT=3330 , VOLUME=SER= 
UNIT=23 1 4 , VOLUME=SER= 
DSNAME=UNLDSET1 ,UNIT= 
// VOLUME=SER=001234,DISP=OLD, 
// LABEL=( 1 , SL ) , DCB=( DEN=1 , TRTCH=C ) 
//SYSIN DD * 

MOVE DSNAME=UNLDSET1 ,T0=23 

FROM=2400-2=( 00 1 234 , 1 ) 

MOVE DSNAME=UNLDSET2,TO=23 

FROM=2400-2=( 00 1 234 , 2 ) 

MOVE DSNAME=UNLDSET3,TO=23 

FROM=2400-2=( 00 1 234 , 3 ) 

/* 



231400,DISP=OLD 
111111 ,DISP=OLD 
231400,DISP=OLD 
2400-2, 



14=231400, 

, FROMDD=TAPESETS 

14=231400, 

, FROMDD=TAPESETS 

14=231400, 

, FROMDD=TAPESETS 



The control statements are discussed below: 

• SYSUTl DD defines the device that is to contain the work data set. 

• ddi DD defines the system residence device. 
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• DD2 DD defines a mountable device on which the receiving volume is 
mounted. 

• TAPESETS DD defines a mountable device on which the source volume is 
mounted. DCB information is provided in this statement. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• MOVE moves the unloaded data sets to the receiving volume. 

Note: To move a data set from a tape volume that contains more than one data 
set, you must specify the sequence number of the data set in the list field of the 
FROM or TO parameter on the utility control statement. 



In this example, two sequential data sets are to be copied from separate source 
volumes to a 2314 volume. Space is allocated by IEHMOVE. Only one 9-track 
tape unit is available for the operation. 



72 



The example follows: 

//DEFER JOB 09#550, GREEN 

// EXEC PGM= IEHMOVE 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD UNIT=2314,VOLUME=SER=231400,DISP=OLD 

//DD1 DD UNIT=2314,VOLUME=SER=111111 ,DISP=OLD 

//DD2 DD UNIT=2314,VOLUME=SER=231400,DISP=OLD 

//TAPE1 DD DSNAME=SEQSET1 ,UNIT=2400 ,DISP=OLD, 

// LABEL=(2,SL) ) , VOLUME=SER=001 234 , 

// DCB=(DEN=2,RECFM=U,BLKSIZE=2000 ) 

//TAPE2 DD DSNAME=SEQSET9,UNIT=AFF=TAPE1 ,DISP=OLD, 

// LABEL=(, SL ) , VOLUME=SER=00 1235, 

// DCB=( DEN=2 , RECFM=FB , LRECL=80 , BLKSIZE=400 ) 

//SYSIN DD * 

COPY DSNAME=SEQSET1 ,TO=23 14=23 1400, C 

FROM=2400=( 00 1 234 , 2 ) , FROMDD=TAPE1 

COPY DSNAME=SEQSET9,TO=23 14=23 1400, C 

FROM=2400=( 001235,4), FROMDD=TAPE2 
/* 

The control statements are discussed below: 

• SYSUTi DD defines the volume that is to contain the work data set. 

• DDl DD defines the system residence device. 

• DD2 DD defines a mountable device on which the receiving volume is 
mounted. 

• TAPEl DD defines a mountable device on which the first volume to be 
processed is mounted. The source data set is the second data set on the 
volume. 

• TAPE2 DD defines a mountable device on which the second volume to be 
processed is mounted when it is required. The source data set is the fourth 
data set on the volume. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• COPY copies the data sets to the receiving volume. 

Note: To copy a data set from a tape volume that contains more than one data 
set, you must specify the sequence number of the data set in the list field off the 
FROM or TO parameter on the utility control statement. 
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In this example, three unloaded partitioned data sets residing on an unlabeled 
tape volume mounted on device 282 are copied to a 2314 volume mounted on 
device 191. 

The example follows: 

//LOAD JOB MEDDAUGH,PS40 300439, MSGLEVEL=1 

// EXEC PGM= IEHMOVE 

//SYSPRINT DD SYSOUT=A 

//SYSABEND DD SYSOUT=A 

//SYSUT1 DD UNIT=191 ,VOLUME=SER=231400,DISP=OLD 

//DD1 DD UNIT=191,VOLUME=SER=231400,DISP=OLD 

//TAPE1 DD UNIT=282,VOLUME=SER=NL.TAPE,DISP=OLD, 

// LABELS ,NL) 

//SYS IN DD * 

COPY PDS=DSET1 , FROM=2 82= ( NLTAPE, 1 ), TO=1 91=23 1 400 , FROMDD=TAPE1 
COPY PDS=DSET2 , FROM=282=( NLTAPE , 2 ) , TO=1 9 1=231400, FR0MDD=TAPE1 
COPY PDS=DSET3 ,FROM=282=( NLTAPE, 3 ) , T.O=1 91 =23 1 400 , FR0MDD=TAPE1 

/* 

The control statements are discussed below: 

• SYSUTl DD defines the work data set. 

• TAPEl DD defines the source data sets. They are, in the order in which they 
reside on the volume, DSETl, DSET2, and DSET3. 

• DD1 DD defines the receiving volume. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• COPY copies the unloaded partitioned data sets from the unlabeled tape to the 
receiving volume. 

Note: To copy data sets from an unlabeled tape, you must place a label in the list 
field of the FROM parameter of the utility control statement. Following this label, 
the sequence numbers of the data sets must also be included in the same field. 
The unit address must appear in the device field of the FROM or TO parameter 
whenever you want to move from or copy to a specific device. 



21-28 OS/VS Utilities 



IEHPROGM Program for VS1 Release 3 



IEHPROGM is a system utility used to modify system control data and to maintain 
data sets at an organizational level. (See "Introduction" for general system utility 
information.) IEHPROGM can only be used by those programmers locally 
authorized to do so. 

IEHPROGM can be used to: 

• Scratch a data set or a member. 

• Rename a data set or a member. 

• Catalog or uncatalog a data set. 

• Build or delete an index or an index alias. 

• Connect or release two volumes. 

• Build and maintain a generation index. 

• Maintain data set passwords. 

At the completion or termination of the program, the highest return code 
encountered within the program is passed to the calling program. 

Scratching a Data Set or Member 

IEHPROGM can be used to scratch the following from a direct access volume or 
volumes: 

• Sequential, indexed sequential, partitioned, or direct access data sets. 

• Members of a partitioned data set. 

• Password-protected data sets. 

• Data sets named by the operating system. 

A data set is considered scratched when its data set control block is removed 
from the volume table of contents (VTOC) of the volume on which it resides; its 
space is made available for re-allocation. 

The space occupied by a data set residing on a device that operates in 
split-cylinder mode is not available for re-allocation until all data sets sharing the 
cylinder have been scratched. 

A member is considered scratched when its name is removed from the directory 
of the partitioned data set in which it is contained. The space occupied by a 
scratched member is not available for re-allocation until the partitioned data set 
is scratched or compressed. (When scratching a member of a partitioned data set, 
all aliases of that member should also be removed from the directory.) 

Renaming a Data Set or Member 

IEHPROGM can be used to rename a data set or member that resides on a direct 
access volume. In addition, the program can be used to change any member 
aliases. 
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Cataloging or Uncataloging a Data Set 

IEHPROGM can be used to catalog or uncatalog a sequential, indexed sequential, 
partitioned, or data set accessed by using BDAM. A data set is cataloged when its 
fully qualified name and volume identification are entered in one or more index 
levels of the SYSCTLG data set. The program catalogs a data set by generating an 
entry containing the data set name and associated volume information, in the 
index of the catalog. If higher level indexes are necessary to catalog the data set, 
they are automatically created. 

The catalog function is used to: (1) catalog a data set that was not cataloged 
when it was created, or (2) satisfy, if necessary, the requirement that a higher 
level index or indexes be created. Figure 22-1 shows how data set A.F.G is 
cataloged on the system residence volume. Note that the level F index does not 
exist in the SYSCTLG data set before the catalog operation. 



System residence- 
before cataloging A.F.G. 



System residence- 
after cataloging A.F.G. 




YTOC 



L"^~T SYSCTLG - 





Figure 22-1. Cataloging a Data Set Using iehprogm 

The catalog function of IEHPROGM differs from a DISP=(,CATLG) specification in 
a DD statement in that the DISP=(,CATLG) specification cannot create higher 
level indexes and cannot catalog a data set on a volume other than the system 
residence volume unless the system residence volume is properly connected to the 
other volume. (Refer to "Connecting or Releasing Two Volumes" in this chapter 
for a discussion of connected volumes.) 

IEHPROGM uncatalogs a data set by removing the data set name and associated 
volume information from the lowest level index of the catalog. 

The uncatalog function of the program differs from a DISP=(...,UNCATLG) 
specification in a DD statement in that the DISP=(...,UNCATLG) specification 
cannot remove an entry from the sysctlg data set on a volume other than the 
system residence volume unless the two volumes are properly connected. 

Figure 22-2 shows how data set A.F.G is uncataloged by the program. Prior to 
the operation, the fully qualified name and associated volume information are 
represented in the catalog. The uncatalog operation removes the lowest level 
entry from the index structure. Note that the structure A.F remains in the 
catalog. 
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System residence- 
prior to uncataloging A.F.G. 



System residence- 
after uncataloging A.F.G. 





Figure 22-2. Uncataloging a Data Set Using iehprogm 

Building or Deleting an Index 

IEHPROGM can be used to build a new index in the catalog or to delete an 
existing index. In building an index, the program automatically creates as many 
higher level indexes as are necessary to complete the specified structure. 

IEHPROGM can be used to delete one or more indexes from an index structure; 
however, an index cannot be deleted if it contains any entries. That is, it cannot 
be deleted if it refers to a lower level index or if it is part of a structure 
indicating the fully qualified name of a cataloged data set. 

Figure 22-3 shows an index structure before and after a build operation. The 
left-hand portion of the figure shows two cataloged data sets, A.Y.YY and 
A.B.x.XX, before the build operation. The right-hand portion of the figure shows 
the index structure after the build operation, which was used to build index 
A.B.C.D.E. Note in the left-hand portion of the figure that index levels C and D 
do not exist before the build operation. These levels are automatically created 
when the level E index is built. 





A.B.X.XX 




Before build operation After build operation 

Figure 22-3. Index Structure Before and After an IEHPROGM Build Operation 
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When the level E index is subsequently deleted, the level C and D indexes are not 
automatically deleted by the program. To delete these index levels, delete: 
A.B.C.D.E, A.B.C.D, and A.B.C, in that order. The level B index cannot be deleted 
because data set a.b.x.xx and the x level index are dependent upon the level B 
index. 

Building or Deleting an Index Alias 

IEHPROGM can be used to assign an alternative name (alias) to the highest level 
index of a catalog or to delete an alias previously assigned. An alias cannot, 
however, be assigned to the highest level of a generation index. 

Figure 22-4 shows an alias, XX, that is assigned to index A (a high level index). 
The cataloged data set A.B.C can be referred to as either A.B.C or XX.B.C. 




Figure 22-4. Building an Index Alias Using iehprogm 

Connecting or Releasing Two Volumes 

IEHPROGM can be used to connect a volume to a second volume by placing an 
entry into a high level index on the first volume. The entry contains an index 
name and the volume serial number and device type of the second volume. The 
program can subsequently release the volumes by removing the entry from the 
high level index. If two volumes are connected: 

• The catalog (SYSCTLG data set) must be created on the second volume for 
cataloging of data sets having the same high level index as the connected 
index. 

• Normal JCL can be used to process (catalog, retrieve, uncatalog) data sets 
cataloged on the second volume, if the high level index has been connected 
from the first volume. 

• A high level index can only be connected to one second volume, but chaining 
is possible from a second to a third volume, etc. 

If the SYSCTLG data set is extended to a second volume, it must be identified on 
that volume. 

Figure 22-5 shows how the system residence volume can be connected to a 
second volume. Any subsequent index search for index X on the system residence 
volume is carried to the second volume. 
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System residence volume 



Connected volume 




Figure 22-5. Connecting a Volume to a Second Volume Using iehprogm 

Note: The index name of each high level index existing on the second volume 
must be present in the first volume; when a new high level index is placed on a 
second volume, the first volume should be connected to the second volume. 

Figure 22-6 shows three volumes connected to the system residence volume. All 
volumes are accessible (through high level indexes X, Y, and Z) to the operating 
system. 



System residence 



System residence 





Figure 22-6. Connecting Three Volumes Using IEHPROGM 

Building and Maintaining a Generation Index 

IEHPROGM can be used to build an index structure for a generation data group 
and to control the action to be taken should the index overflow. 

The lowest level index in the structure can contain up to 255 entries for 
successive generations of a data set. If the index overflows, the oldest entry is 
removed from the index, unless otherwise specified (in which case all entries are 
removed). If desired, the program can be used to scratch all generation data sets 
whose entries are removed from the index. 

Figure 22-7 shows the index structure created for generation data group A.B.C. In 
this example, provision is made for up to five subsequent entries in the lowest 
level index. 
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Figure 22-7, Building a Generation Index Using iehprogm 

Note: Before a generation data group can be cataloged as such, a generation 
index must exist. Otherwise, a generation data set is cataloged as an individual 
data set, rather than as a generation. 

When creating and cataloging a generation data set, the user can provide 
necessary DCB information. See OS/VS Data Management Services Guide, GC 
26-3783. for a discussion of how DCB attributes are provided for a generation 
data group. 

Maintaining Data Set Passwords 

iehprogm can be used to maintain password entries in the PASSWORD data set 
and to alter the protection status of direct access data sets in the data set control 
block (dscb). For a complete description of data set passwords and the 
PASSWORD data set, see OS/VS Data Management for System Programmers, 
GC28-0631, and OS/VS Data Management Services Guide, GC26-3783. 

A data set can have one of three types of password protection, as indicated in 
the dscb for direct access data sets and in the tape label for tape data sets (see 
0S/VS1 System Data Areas, SY28-0605, for a description of the DSCB and tape 
label). The possible types of data set password protection are: 

• No protection, which means that no passwords are required to read or write 
the data set. 

• Read/write protection, which means that a password is required to read or 
write the data set. 

• Read-without-password protection, which means that a password is required 
only to write the data set; the data set can be read without a password. 

Note: If a system data set is password protected and a problem occurs on the 
data set, maintenance personnel must be provided with the password in order to 
access the data set and resolve the problem. 

A data set can have one or more passwords assigned to it; each password has an 
entry in the password data set. A password assigned to a data set can allow 
read and write access or only read access to the data set. 
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Figure 22-8 shows the relationship between the protection status of data set ABC 
and the type of access allowed by the passwords assigned to the data set. 
Passwords ABLE and BAKER are assigned to data set ABC. If no password 
protection is set in the DSCB or tape label, data set ABC can be read or written 
without a password. If read/write protection is set in the DSCB or tape label, 
data set ABC can be read with either password ABLE or baker and can be 
written with password ABLE. If read-without-password protection is set in the 
DSCB or tape label, data set ABC can be read without a password and can be 
written with password able; password BAKER is never needed. 



Protection status of data 
set ABC— contained in 
its DSCB or tape label 



No 

password 

protection 



Read/Write 
protection 



Read-without 

password 

protection 



The kind of protection pointed 
at allows data set ABC to be: 



. Read or written on with 
no password 



with 



BAKER . 

' ■ ■ ■ Read or written on with 
paTswSttt ABLE 



#1»8<*-. 



, Read with 
no password 



Password BAKER 
allows read access 



Password ABLE foi 
allows read/write ai 




Figure 22-8. Relationship Between the Protection Status of a Data Set and Its 
Passwords 

Before IEHPROGM is used to maintain data set passwords, the PASSWORD data 
set must reside on the system residence volume. IEHPROGM can then be used to: 

• Add an entry to the PASSWORD data set. 

• Replace an entry in the PASSWORD data set. 

• Delete an entry from the password data set. 

• Provide a list of information from an entry in the PASSWORD data set. 

Each entry in the PASSWORD data set contains the name of the protected data 
set, the password, the protection mode of the password, an access counter, and 
77 bytes of optional user data. The protection mode of the password defines the 
type of access allowed by the password and whether the password is a control 
password or secondary password. The initial password, added to the PASSWORD 
data set for a particular data set, is marked in the entry as the control password 
for that data set. The second and subsequent passwords added for the same data 
set are marked as secondary passwords. 

For direct access data sets, IEHPROGM updates the protection status in the DSCB 
when a control password entry is added, replaced, or deleted. This permits setting 
and resetting the protection status of an existing direct access data set at the; 
same time its passwords are added, replaced, or deleted. IEHPROGM automatically 
alters the protection status of a data set in the DSCB if the following conditions 
are met: 

• The control password for the data set is being added, replaced, or deleted. 

• The data set is online. 

• The volume on which the data set resides is specified on the utility control 
statement, or the data set is cataloged. 

• The data set is not allocated within the IEHPROGM job. 
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For tape data sets, IEHPROGM cannot update the protection status in the tape 
label when a password entry is added, replaced, or deleted. Protection status in a 
tape label must be set with JCL. 

Passwords to be added, replaced, deleted, or listed can be specified on utility 
control statements or can be entered by the console operator. IEHPROGM issues a 
message to the console operator when a password on a utility control statement 
is either missing or invalid. The message contains the job name, step name, and 
utility control statement name and identifies the particular password that is 
missing or invalid. Two invalid passwords are allowed per password entry on 
each utility control statement before the request is ignored; a total of five invalid 
passwords is allowed for the password entries on all the utility control statements 
in a job step before the step is canceled. 

Adding Data Set Passwords 

When a password is added for a data set, an entry is created in the PASSWORD 
data set with the specified data set name, password name, protection mode of the 
password (read/ write or read only), and the optional 77 characters of 
user-supplied data. The access counter in the entry is set to zero. 

The control password for a data set must always be specified to add, replace, or 
delete secondary passwords. The control password should not be specified, 
however, to list information from a secondary password entry. 

Secondary passwords can be assigned to a data set to restrict some users to 
reading the data set or to record the number of times certain users access the 
data set. The access counter in each password entry provides a count of the 
number of times the password was used to successfully open the data set. 

If a control password for a direct access, online data set is added, the protection 
status of the data set (read/write or read-without-password) is set in the DSCB. 
However, the data set to be protected must not be allocated within the same job 
as the one in which IEHPROGM is executed. If it is allocated, the DSCB cannot be 
accessed and the protection status is not set. If the data set to be protected is 
being created within the same job, use JCL to set the protection status in the 

DSCB. 

Replacing Data Set Passwords 

Any of the following information may be replaced in a password entry: the 
password, protection mode (read/write or read only) of the password, and the 77 
characters of user data. The access counter of the password entry is set to zero 
when any information in the entry is replaced. The protection status of a data set 
can be changed by replacing the control entry for the data set. 

If the control entry of a direct access, online data set is replaced, the DSCB is 
also reset to indicate any change in the protection status of the data set. 
Therefore, the user should ensure that the volume is online when changing the 
protection status of a direct access data set. 

Deleting Data Set Passwords 

When a control password entry is deleted from the PASSWORD data set, all 
secondary password entries for that data set are also deleted. However, when a 
secondary entry is deleted, no other password entries are deleted. 
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Listing Password Entries 



Input and Output 



Control 



If the control password entry is deleted for an online, direct access data set, the 
protection status of the data set in the DSCB is also changed to indicate no 
protection. When deleting a control password for a direct access data set, the 
user should ensure that the volume is online. If the volume is not online, the 
password entry is removed, but data set protection is still indicated in the DSCB; 
the data set cannot be accessed unless another password is added for that data 
set. 

If the control password entry is deleted for a tape data set, the user must change 
the protection status in the tape label to indicate no protection; otherwise, the 
data set cannot be accessed. The tape label may be changed using the IEHINITT 
utility program. 

The delete function should be used to delete all the password entries for a 
scratched data set to make the space available for new entries. 



A list of information from any entry in the PASSWORD data set can be obtained 
in the SYSPRINT data set by providing the password for that entry. The list 
includes: the number of times the password has been used to successfully open 
the data set; the type of password (control password or secondary password) and 
type of access allowed by the password (read/ write or read-only); and the user 
data in the entry. Figure 22-9 shows a sample list of information printed from a 
password entry. 

DECIMAL ACCESS COUNT= 000025 

PROTECT MODE BYTE= SECONDARY, READ ONLY 

USER DATA FIELD= ASSIGNED TO J. BROWN 

Figure 22-9. Listing of a Password Entry 



IEHPROGM uses as input a control data set that contains utility control 
statements used to control the functions of the program and to indicate those 
data sets or volumes that are to be modified. 

IEHPROGM produces as output a modified object data set or volume(s), and a 
message data set that contains error messages and information from the 
PASSWORD data set. 

IEHPROGM provides a return code to indicate the results of program execution. 
The return codes and their meanings are: 

• 00, which indicates successful completion. 

• 04, which indicates that a syntax error was found in the name field of the 
control statement or in the parm field in the EXEC statement. Processing is 
continued. 

• 08, which indicates that a request for a specific operation was ignored because 
of an invalid control statement or an otherwise invalid request. The operation 
is not performed. 

• 12, which indicates that an input/output error was detected when trying to 
read from or write to SYSPRINT, SYSIN or the VTOC. 

• 16, which indicates an unrecoverable error. The job step is terminated. 



IEHPROGM is controlled by job control statements and utility control statements. 
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Job control statements are used to: 

• Execute or invoke the program. 

• Define the control data set. 

• Define volumes and/or devices to be used during the course of program 
execution. 

• Prevent data sets from being deleted inadvertently. 

• Prevent volumes from being demounted before they have been completely 
processed by the program. 

• Suppress listing of utility control statements. 

Utility control statements are used to control the functions of the program and to 
define those data sets or volumes that are to be modified. 

Job Control Statements 

Table 22-1 shows the job control statements necessary for using IEHPROGM. 

Table 22-1. iehprogm Job Control Statements 

Statement Use 

JOB Ihitiates the job. 

EXEC Specifies the program name (PGM-IEHPROGM) or, if the job control 

statements reside in a procedure library, the procedure name. Additional 
PARM information can be specified to control the number of lines per page 
on the output listing and to suppress printing of utility control statements. 
See "parm Information on the EXEC Statement" below., 

SYSPRINT DD Defines a sequential message data set. 

anynamel DE) Defines a permanently mounted volume. (The system residence volume is 
considered to be a permanently mounted volume.) 

anyname2 DD Defines a mountable device type. 

SYSIN DD Defines the control data set. The control data set normally follows the job 

control statements in the input stream; however, it can be defined as a 
member of a procedure library. 

The anynamel DD statement can be entered: 

//anynamel DD UNIT=xxxx,VOLUME=SER=xxxxxx,DISP-OLD 

The UNIT and VOLUME parameters define the device type and volume serial 
number. The disp=OLD specification prevents the inadvertent deletion of a data 
set. The anynamel DD statement is arbitrarily assigned the ddname DDl in the 
IEHPROGM examples. 

The anyname2 DD statement can be coded in the following ways: 

//anyname2 DD VOLUME=SER=xxxxxx,UNIT-xxxx,DISP-OLD 

//anyname2 DD VOLUME=(PRIVATE,SER«xxxxxx), 
// UNIT=(xxxx„DEFER),DISP-OLD 

The second example can be used to specify deferred mounting when a large 
number of magnetic tapes or direct access volumes are to be processed in one 
application of the program. The anyname2 DD statement is arbitrarily assigned 
the ddname DD2 in the iehprogm examples. DD statements defining additional 
mountable devices are assigned names DD3, DD4, etc. 

Refer to "Appendix C: DD Statements for Defining Mountable Devices" for 
instructions on defining mountable volumes. 
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Restrictions 

• The block size for the SYSPRINT (message) data set must be a multiple of 
121. The block size for the SYSIN (control) data set must be a multiple of 80. 
Any blocking factor can be specified for these block sizes. 

• With the exception of the SYSIN and SYSPRINT DD statements, all DD 
statements in Table 22-1 are used as device allocation statements, rather than 
as true data definition statements. Because IEHPROGM modifies the internal 
control blocks created by device allocation DD statements, these statements 
must not include the DSNAME parameter. (All data sets are defined explicitly 
or implicitly by utility control statements.) 

• One anynamel DD statement must be included for each permanently mounted 
volume referred to in the job step. 

• One anyname2 DD statement must be included for each mountable device to 
be used in the job step. 

• When IEHPROGM is dynamically invoked in a job step containing a program 
other than IEHPROGM, the DD statements defining mountable devices for 
IEHPROGM must be included in the job stream prior to DD statements defining 
data sets required by the other program. 

PARM Information on the EXEC Statement 

Additional information can be specified in the PARM parameter of the EXEC 
statement to control the number of lines per page on the output listing and to 
suppress printing of utility control statements. The EXEC statement can be coded: 

// EXEC PGM=IEHPROGM[,PARM='LINECNT=xx, { PRINT } 

{NOPRINT}'] 

The LINECNT parameter specifies the number of lines per page in the listing of 
the SYSPRINT data set; xx is a 2-digit number, from 01 through 99. If LINECNT 
is omitted, or if an error is encountered in the LINECNT subparameter, the 
number of lines per page will be 45. 

The PRINT value specifies that the utility control statements are to be written to 
the SYSPRINT data set. If neither PRINT nor NOPRINT is coded, PRINT is 
assumed. 

The NOPRINT value specifies that utility control statements are not to be written 
to the SYSPRINT data set. Suppressing printing of utility control statements 
assures that passwords assigned to data sets remain confidential. However, 
suppressing printing may make it difficult to interpret error messages because the 
relevant utility control statement is not printed before the message. 

Utility Control Statements 

IEHPROGM is controlled by the following utility control statements: 

• SCRATCH statement, which is used to scratch a data set or a member from a 
direct access volume. 

• RENAME statement, which is used to change the name or alias of a data set or 
member residing on a direct access volume. 

• CATLG statement, which is used to generate an entry in the index of a catalog. 

• UNCATLG statement, which is used to remove an entry from the lowest level 
index of the catalog. 

• BLDX statement, which is used to create a new index in the catalog. 

• DLTX statement, which is used to remove a low level index from the catalog. 
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BLDA statement, which is used to assign an alias to an index at the highest 
level of the catalog. 

DLTA statement, which is used to delete an alias previously assigned to an 
index at the highest level of the catalog. 

CONNECT statement, which is used to place an entry into an index at the 
highest level of the catalog. 

RELEASE statement, which is used to remove an entry from the high level 
index of a volume. 

BLDG statement, which is used to build an index for a generation data group 
and to establish the action to be taken should the index overflow. 

ADD statement, which is used to add a password entry in the PASSWORD data 
set. 

REPLACE statement, which is used to replace information in a password entry. 

DELETEP statement, which is used to delete an entry in the PASSWORD data 
set. 

LIST statement, which is used to format and list information from a password 
entry. 



SCRATCH Statement 



The SCRATCH statement is used to scratch a data set or member from a direct 
access volume. A data set or member is scratched only from the volumes 
designated in the SCRATCH statement. This function does not uncatalog 
scratched data sets. 

The format of the SCRATCH statement is: 



[label] SCRATCH 



{DSNAME=name} 
{VTOC} 

,VOL=deWce=//st 
[,PURGE] 

[,MEMBER=name] 
[,SYS] 



where: 



DSNAME=name 

specifies the fully qualified name of either the data set to be scratched or the 
partitioned data set that contains the member to be scratched. 

VTOC 

specifies that all data sets on the specified volume, except those protected by a 
password or those whose expiration dates have not expired, are to be 
scratched. Password-protected data sets are scratched if the correct password 
is provided. The effect of VTOC is modified when it is used with PURGE or 
SYS. 

VOL=dew'ce= list 

specifies the volume or volumes that contain the data set or sets to be 
scratched. If VTOC is specified, VOL cannot specify more than one volume. The 
list must not contain more than 50 volumes in any other cases. Caution should 
be used when specifying VTOC if VOL specifies the system residence volume. 



22-12 OS/VS Utilities 



RENAME Statement 



CATLG Statement 



PURGE 

specifies that each data set specified by DSNAME or VTOC be scratched, even if 
its expiration date has not elapsed. If PURGE is omitted, the specified data sets 
are scratched only if their expiration dates have elapsed. 

MEMBER= name 

specifies a member name or alias of a member to be removed from the 
directory of a partitioned data set. If MEMBER is omitted, the entire data set 
or volume of data sets is scratched. 

SYS 

specifies that data sets that are to be scratched have names that begin with 
"AAAAAAAA.AAAAAAAA.AAAAAAAA.AAAAAAAA." or "SYSnnnnn.T" and "F" 
or "v" in position 19. These are names assigned to data sets by the operating 
system. This parameter is valid only when VTOC is specified. 

If the name of the data set to be scratched begins with SYS, nnnnn is the date. 

When executing a SCRATCH operation, care should be taken to ensure that the 
data set or volume is not being used by a program executing concurrently. 



The RENAME statement is used to change the true name or alias of a data set or 
member residing on a direct access volume. The name is changed only on the 
designated volume(s). The rename operation does not update the catalog. 

The format of the RENAME statement is: 



[label] RENAME 



DSNAME= name 
,VOL=dew'ce=//st 
,NEWNAME=name 
[,MEMBER= name] 



where: 



DSNAME=name 

specifies the fully qualified name of the data set to be renamed or specifies the 
data set that contains the member to be renamed. 

VOL=dewce=//st 

specifies the volume or volumes that contain the data set or member whose 
name is to be changed. If MEMBER is specified, VOL cannot specify more than 
one volume. The list must not contain more than 50 volumes in any other 
case. 

NEWNAME=name 

specifies the new fully qualified name for the data set, or the new member or 
alias. 

MEMBER= name 

specifies the name or alias for a member (in the named data set) that is to be 
renamed. If MEMBER is omitted, the specified data set name is changed. 



The CATLG statement is used to generate an entry in the index of a catalog. If 
additional levels of indexes are required in the catalog, this function automatically 
creates them. When cataloging generation data sets, refer to "BLDG (Build 
Generation Index) Statement" for the action to be taken when the index is full. 
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The format of the CATLG statement is: 



[label] CATLG 



UNCATLG Statement 



DSNAME=name 

,VOL=dew'ce=/»st 

[,CVOL=dev/ce=ser/a/] 



where: 



DSNAME= name 

specifies the fully qualified name of the data set to be cataloged. The qualified 
name must not exceed 44 characters, including delimiters. 

VOL=cteWce=//st 

specifies the volume or volumes that contain the data set to be cataloged. For 
either a sequential data set or an indexed sequential data set, the volume serial 
numbers must appear in the same order in which they were originally 
encountered (in DD statements within the input stream) when the data set was 
created. All serial numbers specified in vol must represent the same device 
type. The list must not contain more than 50 volumes. 

C\OL=device=serial 

specifies the device type and volume serial number of the control volume on 
which the catalog search for the index is to begin. If CVOL is omitted, the 
system residence volume is assumed. If the volumes are connected at the 
highest level of the index and the control volume is mounted, CVOL need not 
be specified. 

Note: When device is represented by a group name (for example, SYSDA) instead 
of a generic name (for example, 2314 or 2400) in the VOL parameter, the catalog 
operation does not enter the device type code in the system catalog. Instead, it 
places a unique entry in the device type field of the catalog. The allocation of the 
device for this entry may not be satisfactory to the user. The generic name 
should be used if the group name was generated for one or more device types. 
When the system is subsequently generated, this entry may no longer be valid; 
that is, all such group name entries should be uncataloged and then recataloged 
after a subsequent generation of the system. 

When cataloging data sets residing on tape, specify the data set sequence number 
and the volume serial number, as follows: 

VOL=device==({serial,seqno},...) 

If a data set is created on a 9-track dual density tape unit (2400-4), the data set 
can be cataloged with a device specification of 2400 for an 800 bits per inch 
tape or 2400-3 for a 1600 bits per inch tape. If a device specification of 2400-4 
is made when the data set is cataloged, any subsequent retrieval of that data set 
is made on a dual density unit. 



The UNCATLG statement is used to remove an entry from the lowest level index 
of the catalog. This function does not delete higher level indexes from the index 
structure. 

The format of the UNCATLG statement is: 

[label] UNCATLG DSNAME=name 

[,CVOL=deWce=seria/] 

where: 

DSNAME==name 

specifies the fully qualified name of the data set to be uncataloged. 
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CVOL=dev/ce=ser/a/ 

specifies the device type and volume serial number of the control volume at 
which the search for the catalog entry is to begin. If CVOL is omitted, the 
system residence volume is assumed. If catalogs are properly connected at the 
highest level of the index and the control volume is mounted, CVOL need not 
be specified. 

BLDX (Build Index) Statement 

The BLDX statement is used to create a new index in the catalog. If the creation 
of an index requires that higher level indexes be created, this function 
automatically creates them. 

The format of the BLDX statement is: 

[label] BLDX INDEX=name 

[,CVOL=dew'ce=ser/a/] 

where: 

INDEX** name 

specifies the qualified name of the index to be created. The qualified name 
must not exceed 44 characters, including delimiters. 

CVOL=dew'ce=ser/a/ 

specifies the device type and volume serial number of the control volume on 
which the search for the index is to begin. If CVOL is omitted, the system 
residence volume is assumed. 

DLTX (Delete Index) Statement 

The DLTX statement is used to remove an index from the catalog. Only an index 
that has no entries can be removed. 

The format of the dltx statement is: 

[label] DLTX INDEX=name 

[,CVOL=deWce=serfa/] 

where: 

INDEX=name 

specifies the qualified name of the index to be deleted. The qualified name 
must not exceed 44 characters, including delimiters. 

CVOL=dev/ce=seria/ 

specifies the device type and volume serial number of the control volume on 
which the search for the index is to begin. If CVOL is omitted, the system 
residence volume is assumed. 

Because this function does not delete higher level indexes, it must be used 
repetitively to delete an entire structure. For example, to delete index structure 
A.B.C, delete index A.B.C, index A.B, and index A. 

BLDA (Build Index Alias) Statement 

The BLDA statement is used to assign and alias to an index at the highest level of 
the catalog. 

The format of the BLDA statement is: 

[label] BLDA INDEX=name 
,ALIAS= name 
[,CVOL=deWce=ser/a/] 
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where: 

INDEX= name 

specifies the unqualified name of the index to which an alias name is to be 
assigned. The unqualified name must not exceed 8 characters. 

ALIAS= name 

specifies an unqualified name to be assigned as the alias. The unqualified name 
must not exceed 8 characters. 

CVOL=dewce=ser/a/ 

specifies the device type and volume serial number of the control volume on 
which the catalog entry is to be made. If CVOL is omitted, the system 
residence volume is assumed. 

DLTA (Delete Index Alias) Statement 

The DLTA statement is used to delete an alias previously assigned to an index at 
the highest level of the catalog. 

The format of the DLTA statement is: 

[label] DLTA ALIAS=name 

[,C VOL = device = serial] 

where: 

ALIAS= name 

specifies the unqualified name of the index alias to be deleted. The unqualified 
name must not exceed 8 characters. 

CVOL = device = serial 

specifies the device type and volume serial number of the control volume 
containing the catalog entry to be deleted. If CVOL is omitted, the system 
residence volume is assumed. 



CONNECT Statement 



The CONNECT statement is used to place an entry in the high level index of the 
catalog. The entry identifies a second volume by its device type and volume serial 
number. In addition, it contains an index name identifying the index to be 
searched for (during subsequent index searches) on the second volume. 

Note: This function does not create an index on the second volume. 

The format of the CONNECT statement is: 

[label] CONNECT INDEX=name 

,VOL=deWce=ser/a/ 
[,CVOL=dewce=ser/a/] 

where: 

INDEX=name 

specifies the unqualified index name to be entered in the high level index on 
the first volume. The unqualified name must not exceed 8 characters. 

VOL=dewce=ser/a/ 

specifies the device type and volume serial number of the second volume. This 
information is placed in the high level index on the first volume. 

CVOL=deWce=sena/ 

specifies the device type and serial number of the first volume. If CVOL is 
omitted, the system residence volume is assumed to be the first volume. 
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The CONNECT statement does not create a SYSCTLG data set on the connected 
volume. Before cataloging the first data set on a connected volume, the user must 
define a SYSCTLG data set on that volume y This can be done with the following 
DD statement: 

//ddname DD DSNAME=SYSCTLG,UNIT=xxxx,DISP=(,KEEP), 
// SPACE=(CYL,l),VOLUME=SER=xxxxxx 

If a job requires an auxiliary control volume to complete a catalog search, the 
user need not have the auxiliary control volume mounted before the job is begun. 
(The user does not have to remember the volume on which a particular data set 
is cataloged.) The system directs the operator to mount an auxiliary control 
volume if it is needed. 

However, the auxiliary control volume must be connected to the system residence 
volume by means of the CONNECT verb, as modified for Release 17 of OS. If an 
auxiliary control volume was connected before Release 17 of OS, release the 
auxiliary control volume for all high level indexes on the system residence volume 
that point to that volume, and then use the current CONNECT verb to reconnect 
the auxiliary control volume with the system residence volume. 



RELEASE (Disconnect) Statement 



The RELEASE statement is used to remove an entry from the high level index of 
a volume. This disconnects, in effect, a second volume from the first volume. The 
RELEASE statement does not delete an index from the second volume. 

The format of the RELEASE statement is: 

[label] RELEASE INDEX=name 

[,CVOL=deWce=ser/af] 

where: 

INDEX=name 

specifies the unqualified index name to be removed from the high level index 
of the first volume. The unqualified name must not exceed 8 characters. 

CVOL=dew'ce=ser/a/ 

specifies the device type and volume serial number of the first volume. If CVOL 
is omitted, the system residence volume is assumed to be first volume. 



BLDG (Build Generation Index) Statement 



The BLDG statement is used to build an index for a generation data group, and 
to establish the action to be taken should the index overflow. 

The format of the BLDG statement is: 

[label] BLDG INDEX=name 
,ENTRIES=n 
[,CVOL=dewce=ser/a/] 
[,EMPTY] 
[,DELETE] 

where: 

INDEX=name 

specifies the 1- to 3 5 -character qualified name of the generation index. 

ENTRIES=n 

specifies the number of entries to be contained in the generation index; n must 
not exceed 255. 



IEHPROGM Program for VS1 Release 3 22-17 



C VOL = device = serial 

specifies the device type and volume serial number of the volume on which the 
catalog search for the index is to begin. If CVOL is omitted, the system 
residence volume is assumed. 

EMPTY 

specifies that all entries be removed from the generation index when it 
overflows. This uncatalogs, in effect, all of the generation data sets. If EMPTY 
is omitted, the entries with the largest generation numbers will be maintained 
in the catalog when the generation index overflows. 

DELETE 

specifies that generation data sets are to be scratched after their entries are 
removed from the index. If DELETE is omitted, the data sets are not scratched. 

ADD (Add a Password) Statement 

The ADD statement is used to add a password entry in the PASSWORD data set. 
When the control entry for a direct access, online data set is added, the indicated 
protection status of the data set is set in the DSCB; when a secondary entry is 
added, the protection status in the DSCB is not changed. 

The format of the ADD statement is: 
[label] ADD DSNAME= name 

[,PASWORD2 = new-password] 

[,CPASWORD=contro/-password] 

[,TYPE=code] 

[,VOL=deWce=//st] 

[,DATA= 'user-data'] 

where: 

DSNAME=name 

specifies the fully qualified name of the data set to which the password is to 
be assigned. 

PASWORD2 = new -pass word 

specifies the password to be added. The password can consist of one- to 
eight-alphameric characters. If PASWORD2 is omitted, the operator is prompted 
for a new password. 

CPASWORD = control-password 

specifies the control password for the data set. The control password must be 
specified unless this is the first password assigned to the data set. 

TYPE= code 

specifies the protection code of the password and, if a control password is 
being assigned to a direct access, online data set, specifies the protection 
status of the data set. If this parameter is omitted, the new password is 
assigned the same protection code as the control password for the data set. If 
a control password is being added, TYPE- 3 is the default. The values that can 
be specified for code are: 

1 

specifies that the password is to allow both read and write access to the 
data set; if a control password is being assigned, read/ write protection is 
set in the DSCB. 

2 

specifies that the password is to allow only read access to the data set; if a 
control password is being assigned, read/ write protection is set in the DSCB. 
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3 

specifies that the password is to allow both read and write access to the 
data set; if a control password is being assigned, read- without-pass word 
protection is set in the DSCB. 

VOL=dev/ce= list 

specifies the direct access volume or volumes that contain the data set to be 
protected. If omitted, the protection status of the data set is not set in the 
DSCB, unless the data set is cataloged. This parameter is not necessary for 
secondary password entries or if the desired protection status is already set in 
the DSCB. The list must not contain more than 50 volumes. 

DATA= 'user-data' 

specifies that user data is to be included in the password entry. The user data 
must be in single quotes and must not exceed 77 characters. 

REPLACE (Replace a Password) Statement 

The REPLACE statement is used to replace any or all of the following information 
in a password entry: the password name, protection mode (read/write or read 
only) of the password, and user data. When the control entry for a direct access, 
online data set is replaced, the protection status of the data set is changed in the 
DSCB if necessary; when a secondary entry is replaced, the protection status in 
the DSCB is not changed. 

The format of the REPLACE statement is: 

[label] REPLACE DSNAME= name 

[,PASWORDl =current-password] 
[,PASWORD2 = new -pass word] 
[,CPASWORD = control-password] 
[,TYPE=code] 
[,VOL=deWce=//st] 
[,DATA= 'user -data*] 

where: 

DSNAME=name 

specifies the fully qualified name of "the data set whose password entry is to be 
changed. 

PASWORD1 =current-password 

specifies the current password in the entry to be changed. If PASWORDl is 
omitted, the operator is prompted for the current password. 

PASWORD2 = new-password 

specifies the new password to be assigned to the entry. If the password is not 
to be changed, the current password must also be specified as the new 
password. The password can consist of one- to eight-alphameric characters. If 
PASWORD2 is omitted, the operator is prompted for a new password. 

CPASWORD=conrro/- password 

specifies the control password for the data set whose entry is to be changed. 
The control password must be specified unless the control entry is being 
changed. If the control entry is to be changed, the control password must be 
specified as PASWORDl. 
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TYPE=cocte 

specifies the protection code of the password and, if a control password entry 
is to be changed for a direct access, online data set, specifies the protection 
status of the data set. If this parameter is omitted, the protection is not 
changed. The values that can be specified for code are: 

1 

specifies that the password is to allow both read and write access to the 
data set; if a control password is being changed, read/write protection is set 
in the DSCB. < 

2 

specifies that the password is to allow only read access to the data set; if a 
control password is being changed, read/ write protection is set in the DSCB. 

3 

specifies that the password is to allow both read and write access to the 
data set; if a control password is being changed, read-without-password 
protection is set in the DSCB. 

VOL=dev/ce=//st 

specifies the direct access volume or volumes that contain the data set whose 
protection status is to be changed. If omitted, the protection status of the data 
set is not changed in the DSCB, unless the data set is cataloged. This 
parameter is not necessary for secondary password entries or if the protection 
status of the data set is not to be changed. The list must not contain more 
than 50 volumes. 

DATA= 'user-data' 

specifies that user data is to be included in the password entry. The user data 
must be in single quotes and must not exceed 77 characters. If this parameter 
is omitted, the user data is not changed. 

DELETEIP (Delete a Password) Statement 

The DELETEP statement is used to delete an entry in the PASSWORD data set. If 
a control entry is deleted, all the secondary entries for that data set are also 
deleted. If a secondary entry is deleted, only that entry is deleted. When the 
control entry for a direct access, online data set is deleted, the protection status 
in the DSCB is set to indicate that the data set is no longer protected. 

The format of the DELETEP statement is: 
[label] DELETEP DSNAME=name 

[,PASWORDl = current-password] 
[,CPASWORD = control-password] 
[,VOL=dev/'ce=//st] 

where: 

DSNAME== name 

specifies the fully qualified name of the data set whose password is to be 
deleted. 

PASWORD1 =current-password 

specifies the password to be deleted. 

CPASWORD=contro/-password 

specifies the control password for the data set whose password is to be 
deleted. The control password must be specified unless the control password is 
to be deleted. If the control password is to be deleted, the control password 
must be specified as PASWORDl. 
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VOL=dew'ce= list 

specifies the direct access volume or volumes that contain the data set whose 
password is to be deleted. If omitted, the protection status of the data set is 
not changed in the DSCB, unless the data set is cataloged. This parameter is 
not necessary if a secondary password is to be deleted. 

LIST (List Information from a Password) Statement 

The LIST statement is used to format and print information from a password 
entry. 

The format of the LIST statement is: 

[label] LIST DSNAME=name 

,PASWORDl -^current-password 

where: 

DSNAME= name 

specifies the fully qualified name of the data set whose password entry is to be 
listed. 

PASWORD1 = current- password 

specifies the password in the entry to be listed. 



IEHPROGM Examples 



The following examples illustrate some of the uses of IEHPROGM. Table 22-2 can 
be used as a quick reference guide to IEHPROGM examples. The numbers in the 
"Example" column point to the examples that follow. 
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IEHPROGM Example 1 



Table 22-2. iehprogm Example Directory 

Mountable 
Operation Volumes Comments Example 

SCRATCH 2314 Disk vtoc is to be scratched. 1 

SCRATCH 2314 Disk Two data sets are to be scratched and 

UNCATLG, uncataloged. An index structure is to be deleted 

and DLTX from SYSCTLG. 2 

RENAME, 2314 Disks A data set is to be renamed on two mountable 
UNCATLG, devices; the old data set name and index 

DLTX, and structure are to be removed from the catalog. The 

CATLG data set is cataloged under its new name. Object 

data set resides on two mountable devices. 3 

UNCATLG 2314 Disk Three data sets are to be uncataloged; their 
and DLTX supporting index structures are to be deleted 

from the catalog. 4 

CONNECT 2314 Disk Connect system residence volume to a second 
and CATLG volume. Catalog data sets on second volume. 

sysctlg was previously defined on the second 
volume. 5 

BLDG None A generation index is to be built. 6 

BLDG and None A generation index is to be built and 

CATLG three data sets are to be cataloged. 7 

RENAME, 2314 Disk The object data set exists on one mountable 

DELETEP, device. 

and ADD 8 

LIST and 2314 Disk The object data set exists on two mountable 

REPLACE devices. 9 

RENAME 2314 Disk Rename a member of a partitioned data set. 10 

BLDG 2314 Disk Create a model DSCB and build a generation index. 

Use IEBGENER to catalog a second generation. 11A 

Create and catalog a second generation in 

index created in 11 A. 11B 

In the iehprogm examples, the exec statement and the SYSPRINT DD statement 
can be replaced with the following job control statement: 

// EXEC PROC=MOD 

which invokes the following IBM-supplied cataloged procedure: 

//MOD EXEC PGM=IEHPROGM,REGION-44K 
//DDSRV DD VOLUME=REF=SYSl.SVCLIB,DISP-OLD 
//SYSPRINT DD SYSOUT=A 

Note: In the iehprogm examples, the DDl DD statement always refers to the 
system residence volume. 



In the following example, data sets are to be scratched from the volume table of 
contents of a mountable volume. Because the system residence volume is not 
referred to, no DDl DD statement is necessary in the job stream. 
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The example follows: 



IEHPROGM Example 2 



IEHPROGM Example 3 



JOB 09#550, BROWN 
EXEC PGM= IEHPROGM 

SYSOUT=A 

UNIT=23 1 4 , VOLUME=SER=23 1 400 , DISP=OLD 

* 

VTOC,VOL=2314=231400 



//SCRVTOC 
// 

//SYSPRINT DD 
//DD2 DD 
//SYSIN DD 
SCRATCH 
/* 

The SCRATCH statement, used in this example, indicates that all data sets 
(including those beginning with AAAAAA.AAAAAA.AAAAAA.AAAAAA) whose 
expiration dates have expired are to be scratched from the specified volume. 



In this example, two data sets are to be scratched: SETl is to be scratched on 
volume 231400, and A.B.C.D.E is to be scratched on volume 231400. Both data 
sets are to be uncataloged, and index structure A.B.C.D is to be deleted from the 
SYSCTLG data set. Because the system residence volume, which resides on a 
3330 volume, is referred to through use of the UNCATLG and DLTX statements, 
a DD statement is included in the input stream. 

The example follows: 



//SCRDSETS JOB 

// EXEC 

//SYSPRINT DD 

//DD1 DD 

//DD2 DD 

//SYSIN DD 

SCRATCH 

UNCATLG 

SCRATCH 

UNCATLG 

DLTX 

DLTX 

DLTX 

DLTX 

/* 



09#550, BROWN 

PGM= IEHPROGM 

SYSOUT=A 

UNIT=3330,VOLUME=SER=1 11111 ,DISP=OLD 

UNIT=23 1 4 , DISP=OLD , VOLUME=SER=23 1 400 

* 

DSNAME=SET1 ,VOL=23 14=23 1 400 

DSNAME=SET1 

DSNAME=A . B . C . D . E , VOL=2 314=231400 

DSNAME=A.B.C.D.E 

INDEX=A.B.C.D 

INDEX=A.B.C 

INDEX=A.B 

INDEX=A 



The control statements are discussed below: 

• The first SCRATCH statement specifies that SETl, which resides on volume 
231400, is to be scratched. 

• The first UNCATLG statement specifies that SETl is to be uncataloged. 

• The second SCRATCH statement specifies that A.B.C.D.E, which resides on 
volume 231400, is to be scratched. 

• The second UNCATLG statement specifies that A.B.C.D.E is to be uncataloged. 

• The DLTX statements remove one level at a time of the remaining A.B.C.D 
index from the catalog. Index level D is removed, then C, B, and A. 



In this example, the name of a data set is to be changed on two mountable 
volumes. The old data set name and index structure are to be removed from the 
catalog and the data set is to be cataloged under its new data set name. 
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IEHPROGM Example 4 



The example follows: 

72 
//RENAMEDS JOB 09 #5 50, BROWN 
// EXEC PGM=IEHPROGM 

//SYSPRINT DD SYSOUT=A 

//DD1 DD VOLUME=SER=111111,UNIT=3330 f DISP=OLD 
//DD2 DD UNIT=( 2314, , DEFER ) ,DISP=OLD, 
// VOLUME=( PRIVATE, SER=( 231400,231401 ) ) 
//SYSIN DD * 

RENAME DSNAME=A.B.C,NEWNAME=NEWSET, C 

VOL=2314=( 231400,231401 ) 
UNCATLG DSNAME=A . B . C 
DLTX INDEX=A.B 
DLTX INDEX=A 
CATLG DSNAME=NEWSET,VOL=2314=( 231400,231401 ) 
/* 

The control statements are discussed below: 

• rename specifies that data set A.B.C, which resides on volumes 231400 and 
231401, is to be renamed NEWSET. 

• UNCATLG specifies that data set A.B.C is to be uncataloged. 

• The DLTX statements remove remaining index levels B and A. 

• CATLG specifies that NEWSET, which resides on volumes 231400 and 231401, 
is to be cataloged. 



In this example, three data sets — A.B.C.D.E.F.SETl, A.B.C.G.H.SET2, and 
A.B.I.J.K.SET3 — are to be uncataloged and their supporting index structures 
deleted from the catalog. The system residence volume resides on a 2314 volume. 

The example follows: 



//DLTSTRUC JOB 


09#550, BROWN 


// EXEC 


PGM=IEHPROGM 


//SYSPRINT DD 


SYSOUT=A 


//DD1 DD 


UNIT=2314,VOLUME=SER=1 11111 ,DISP=OLD 


//SYSIN DD 


* 


UNCATLG 


DSNAME=A . B . C . D . E . F . SET 1 


UNCATLG 


DSNAME=A . B . C . G . H . SET2 


UNCATLG 


DSNAME=A . B . I . J . K . SET3 


DLTX 


INDEX=A.B.I.J.K 


DLTX 


INDEX=A.B.I.J 


DLTX 


INDEX=A.B.I 


DLTX 


INDEX=A.B.C.G.H 


DLTX 


INDEX=A.B.C.G 


DLTX 


INDEX=A.B.C.D.E.F 


DLTX 


INDEX=A.B.C.D.E 


DLTX 


INDEX=A.B.C.D 


DLTX 


INDEX=A.B.C 


DLTX 


INDEX=A.B 


DLTX 


INDEX=A 



/* 

The control statements are discussed below: 

• The UNCATLG statements specify that data sets A.B.C.D.E.F.SETl, 
A.B.C.G.H.SET2, and A.B.I.J.K.SET3 are to be uncataloged. 

• The DLTX statements remove one level at a time of the index structures 
associated with the uncataloged data sets. 
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IEHPROGM Example 5 



IEHPROGM Example 6 



IEHPROGM Example 7 



In this example, the system residence volume, which resides on a 3330 volume, is 
to be connected to a second volume. Any subsequent index search for index level 
X, Y, or z will be carried to the second volume. 

The example follows: 



//CONNECT 

// 

//SYSPRINT 
//DD1 
//DD2 
//SYSIN 
CONNECT 
CONNECT 
CONNECT 
CATLG 
CATLG 
CATLG 
/* 



JOB 09#550, BROWN 

EXEC PGM=IEHPROGM 

DD SYSOUT=A 

DD UNIT=3330,VOLUME=SER=1 11111 ,DISP=OLD 

DD UNIT-23 1 4 , VOLUME=SER=23 1 400 , DISP=OLD 

DD * 
INDEX=X,VOL=23 14=23 1400 
INDEX=Y , VOL=23 1 4=23 1 400 
INDEX=Z , VOL=23 1 4=23 1 400 

DSNAME=X . BB . CCC , VOL=23 1 4=23 1 40 1 , CVOL=23 1 4=231 400 
DSNAME=Y . BB . CC , VOL=23 1 4=23 1 40 1 , CVOL=23 1 4=23 1 400 
DSNAME=Z . BB. XT, VOL=23 1 4=23 1 401 , CVOL=23 1 4=23 1 400 



The control statements are discussed below: 

• The CONNECT statements identify the second volume. The specified index 
names, along with the volume identification, are placed on the system 
residence volume. 

• The CATLG statements catalog three data sets (X.BB.CCC, Y.BB.CC, and 
z.bb.xt) on the second volume. Because the volumes are connected before the 
catalog operations are performed, the CVOL parameters are not required in the 
CATLG statements; they are included to bypass the index search on the system 
residence volume. 



In this example, a generation index is to be built into the catalog. The system 
residence volume resides on a 3330 volume. 

The example follows: 

//BLDGDGIX JOB 09 #550, BROWN 
// EXEC PGM= IEHPROGM 

//SYSPRINT DD 



//DD1 DD 
//SYSIN DD 
BLDG 
/* 



SYSOUT=A 

UNIT=3330,VOLUME=SER=1 11111 ,DISP=OLD 

INDEX=A . B . C , ENTRIES= 1 , EMPTY 



The BLDG statement specifies the generation data group A.B.C and makes 
provision for ten entries in the index. All entries are to be removed from the 
index when it overflows. 



In this example, a generation index is to be built and three data sets are to be 
cataloged in the index. The system residence volume resides on a 3330 volume. 
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The example follows: 



//DD1 
//SYSIN 



JOB 09#550, BROWN 
EXEC PGM=IEHPROGM 

SYSOUT=A 

UNIT=3330, VOLUME=SER=1 11111 ,DISP=OLD 

* 

INDEX=A . B . C , ENTRIES=20 , EMPTY 
DSNAME=A .B.C. G000 1 V00 , VOL=23 1 4=23 1 400 
DSNAME=A. B . C . G0002V00 , VOL=23 1 4=23 1 400 
DSNAME=A. B . C . G0003V00 , VOL=23 1 4=23 1 400 



//CTLGDG 

// 

//SYSPRINT DD 

DD 

DD 

BLDG 

CATLG 

CATLG 

CATLG 

/* 

The control statements are discussed below: 

• BLDG specifies the generation data group A.B.C and makes provision for 20 
entries in the index. All entries are to be removed from the index when it 
overflows. 

• The CATLG statements cataloged three generation data sets. The data sets are 
cataloged with absolute generation numbers 1 through 3. 

Figure 22-10 shows the index structure after the three generation data sets are 
cataloged. 



G0003V00 

(latest 

generation) 



G0002V00 
(latest -1) 



G001V00 

(latest -2) 



Figure 22-10. Index Structure After Generation Data Sets Are Cataloged 



IEHPROGM Example 8 



In this example, a data set is to be renamed. The data set passwords assigned to 
the old data set name are to be deleted. Then two passwords are to be assigned 
to the new data set name. 

Note: If the data set is not cataloged, a message indicating that the LOCATE 
macro instruction failed is issued. The return code is 8. 



72 



The example follows: 

//ADDP AS S JOB 09#550, BROWN 

EXEC PGM=IEHPROGM,PARM='NOPRINT' 
//SYSPRINT DD SYSOUT=A 

//DD1 DD VOLUME=( PRIVATE, SER=23 1400 ) ,DISP=OLD, 
// UNIT=( 2314, , DEFER) 
//SYSIN DD * 

RENAME DSNAME=OLD , VOL=23 1 4=23 1 400 , NEWNAME=NEW 
DELETEP DSNAME=OLD , PASWORD 1 =KEY 

ADD DSNAME=NEW,PASWORD2=KEY,TYPE=1 , C 

DATA= ' SECONDARY IS READ' 
ADD DSNAME=NEW , PASWORD2=READ , CPASWORD=KEY , TYPE=2 , C 
DATA=' ASSIGNED TO J. DOE' 
/* 

The control statements are discussed below: 

• DELETEP specifies that the entry for the password KEY is to be deleted. 
Because KEY is a control password in this example, all the password entries 
for the data set name are deleted. The VOL parameter is not needed because 
the protection status of the data set as set in the DSCB is not to be changed; 
read/ write protection is presently set in the DSCB, and read/ write protection is 
desired when the passwords are reassigned under the new data set name. 
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IEHPROGM Example 9 



• The ADD statements specify that entries are to be added for passwords KEY 
and READ. KEY becomes the control password and allows both read and write 
access to the data set. READ becomes a secondary password and allows only 
read access to the data set. The VOL parameter is not needed, because the 
protection status of the data set is still set in the DSCB. 

Note: The operator is required to supply a password to rename the old data set. 



In this example, information from a password entry is to be listed. Then the 
protection mode of the password, the protection status of the data set, and the 
user data are to be changed. 

The example follows: 

72 

//REPLPASS JOB 09 #550, BROWN 

EXEC PGM=IEHPROGM,PARM='NOPRINT' 
//SYSPRINT DD SYSOUT=A 

//DD1 DD UNIT=3330,VOLUME=SER=1 111 11 ,DISP=OLD 
//DD2 DD VOLUME=( PRIVATE, SER=( 231400, 231401 ) ), 
// UNIT=( 2314, , DEFER ),DISP=OLD 
//SYSIN DD * 

LIST DSNAME=A.B.C,PASWORD1=ABLE 
REPLACE DSNAME=A.B.C,PASWORD1=ABLE, C 

PASWORD2=ABLE,TYPE=3, C 

VOL=2314=( 231400,231401 ), C 

DATA='NO SECONDARIES; ASSIGNED TO DEPT 31' 
/* 

The control statements are discussed below: 

• LIST specifies that the access counter, protection mode, and user data from the 
entry for password ABLE are to be listed. Listing the entry permits the 
content of the access counter to be recorded before the counter is reset to 
zero by the REPLACE statement. 

• REPLACE specifies that the protection mode of password ABLE is to be 
changed to allow both read and write access and that the protection status of 
the data set is to be changed to write only protection. The VOL parameter is 
required because the protection status x>f the data set is being changed and the 
data set, in this example, is not cataloged. Because this is a control password, 
the CPASWORD parameter is not required. 



IEHPROGM Example 10 



In this example, a member of a partitioned data set is to be renamed. 

The example follows: 

//REN JOB 09#550,BROWN 

// EXEC PGM= IEHPROGM 

//DD1 DD VOL=SER=23141 1 ,DISP=OLD,UNIT=231 4 

//SYSIN DD * 

RENAME VOL=2 3 14=231411, DSNAME=DATASET , NEWNAME=BC , MEMBER=ABC 
/* 

The control statements are discussed below: 

• DDl DD defines a permanently mounted volume. 

• SYSIN DD defines the input data set, which immediately follows in the input 
stream. 

• RENAME specifies that member ABC in the partitioned data set dataset, 
which resides on a 2314 volume, is to be renamed BC. 
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IEHPROGM Example 11 A 

In this example, an iehprogm job step, stepa, creates a model DSCB and builds 
a generation index. STEP B, an IEBGENER job step, creates and catalogs a 
sequential generation from card input. 

The example follows: 

//BLDINDX JOB 

//STEPA EXEC PGM=IEHPROGM 

//SYSPRINT DD SYSOUT-A 

//BLDDSCB DD DSNAME=A. B. C,DISP=( ,KEEP ) ,SPACE=( TRK, ( ) ) , 

// DCB=( LRECL=80,RECFM=FB,BLKSIZE=800 ), 

// VOLUME=SER=1 11111 ,UNIT=2314 

//SYSIN DD * 

BLDG INDEX=A.B.C,ENTRIES= 10, EMPTY DELETE 
/* 

//STEPB EXEC PGM=IEBGENER 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD DUMMY 

//SYSUT2 DD DSNAME=A.B.C(+1 ) ,UNIT=231 4,DISP=( ,CATLG), 
// VOLUME=SER=23 1 400 , SPACE=( TRK, 20 ) 
//SYSUT1 DD DATA 

(input card data) 
/* 

The control statements are discussed below: 

• BLDDSCB DD creates a model DSCB on the system residence volume. 

• SYSIN DD indicates that a utility control statement (BLDG) is included next in 
the input stream. 

• BLDG specifies the generation data group name A.B.C and makes provision for 
ten entries in the group. When the index is filled, it is to be emptied, and all 
of the generations are to be deleted. 

• SYSUT2 DD defines an output sequential generation. The generation is assigned 
the absolute generation and version number G0001V00 in the index. 

• SYSUTl DD defines the input card data set. 

Any subsequent job that causes the deletion of the generations should include 
DD statements defining the devices on which the volumes containing those 
generations are to be mounted. Each generation for which no DD statement is 
included is uncataloged at that time, but not deleted. 

After the generation data group is emptied, the new generations continue to be 
assigned generation numbers according to the last generation number assigned 
before the empty operation. To reset the numbering operation (that is, to reset to 
G0000V00 or G0001V00), it is necessary to uncatalog all the old generation data 
sets and then rename and recatalog, beginning with G0000V00. 

IEHPROGM Example 11B 

In this part of the example, a second generation is created and cataloged in the 
index built in Example 11 A. DCB attributes are included to override those 
attributes that were specified when the model DSCB was created. 
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The example follows: 

// JOB 

// EXEC PGM=IEBGENER 

//SYSPRINT DD SYSOUT=A 

//SYS IN DD DUMMY 

//SYSUT2 DD DSNAME=A.B.C(+1 ) , UNIT=231 4 ,DISP=( ,CATLG), 

// DCB=(LRECL=80,RECFM=FB,BLKSIZE=1600 ), 

// VOLUME=SER=23 1 40 1 , SPACE=( TRK, 20 ) 

//SYSUT1 DD DATA 

(input data set) 

/* 

The control statements are discussed below: 

• SYSUT2 DD defines an output sequential generation. The generation is assigned 
the absolute generation and version number G0002V00 in the index. The 
specified DCB attributes override those initially specified in the model DSCEi. 
The DCB attributes specified when the model DSCB was created remain 
unchanged; that is, those attributes are applicable when you catalog a 
succeeding generation unless you specify overriding attributes at that time. 

• SYSUTl defines the input card data set. 



IEHPROGM Example 12 



In this example, a generation index for generation data group A.B.C is built. 
Three existing non-cataloged, non-generation data sets are renamed; the renamed 
data sets are cataloged as generations in the generation index. 

The example follows: 

72 
//BLDINDEX JOB 

// EXEC PGM=IEHPROGM 

//SYSPRINT DD SYSOUT=A 

//DD1 DD UNIT=2314,VOLUME=SER=111111 ,DISP=OLD 

//DD2 DD UNIT=( 2314, , DEFER ),DISP=OLD, 

// VOLUME=( PRIVATE, , SER=( 231400 ) ) 
//SYSIN DD * 

BLDG INDEX=A.B.C,ENTRIES=10 

RENAME DSNAME=DATASET1 ,VOL=23 14=23 1400, C 

NEWNAME=A . B . C , G000 1 V00 
RENAME DSNAME=DATASET2,VOL=23 14, 231400, C 

NEWNAME=A .B.C. G0002V00 
RENAME DSNAME=DATASET3 VOL=23 14=23 1400 , C 

NEWNAME=A.B.C.G0003V00 
CATLG DSNAME=A .B.C. G000 1 V00 , VOL=23 1 4=23 1 400 
CATLG DSNAME=A. B . C . G0002V00 , VOL=23 1 4=23 1 400 
CATLG DSNAME=A .B.C. G0003V00 , VOL=23 1 4-231 400 
/* 

The control statements are discussed below: 

• DDl DDD defines the system residence volume on which the SYSCTLG data set 
resides. 

• BLDG specifies the generation group name A.B.C and makes provision for ten 
entries in the index. The oldest generation is to be uncataloged when the index 
becomes full. No generations are to be scratched. 

• The RENAME statements rename three non-generation data sets residing on a 
2314 disk volume. 

• CATLG catalogs the renamed data sets in the generation index. 

Note: Because the DCB parameters were supplied when the non-generation data 
sets were created, no DCB parameters are now specified; therefore, no model 
DSCB is required. 
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IEHPROGM is a system utility used to modify system control data and to maintain 
data sets at an organizational level. (See "Introduction" for general system utility 
information.) IEHPROGM can only be used by those programmers locally 
authorized to do so. 

IEHPROGM can be used to: 

• Scratch a data set or a member. 

• Rename a data set or a member. 

• Catalog or uncatalog a non-vsAM data set. 

• Maintain data set passwords. 

At the completion or termination of the program, the highest return code 
encountered within the program is passed to the calling program. 

Scratching a Data Set or Member 

IEHPROGM can be used to scratch the following from a direct access volume or 
volumes: 

• Sequential, indexed sequential, partitioned, or direct access data sets. 

• Members of a partitioned data set. 

• Password-protected data sets. 

• Data sets named by the operating system. 

A data set is considered scratched when its data set control block is removed 
from the volume table of contents (VTOC) of the volume on which it resides; its 
space is made available for re-allocation. 

The space occupied by a data set residing on a device that operates in 
split-cylinder mode is not available for re-allocation until all data sets sharing the 
cylinder have been scratched. 

A member is considered scratched when its name is removed from the directory 
of the partitioned data set in which it is contained. The space occupied by a 
scratched member is not available for re-allocation until the partitioned data set 
is scratched or compressed. (When scratching a member of a partitioned data set, 
all aliases of that member should also be removed from the directory.) 

Renaming a Data Set or Member 

IEHPROGM can be used to rename a data set or member that resides on a direct 
access volume. In addition, the program can be used to change any member 
aliases. 

Cataloging or Uncataloging a Data Set 

IEHPROGM can be used to catalog or uncatalog a non-VSAM sequential, indexed 
sequential, partitioned, or data set accessed by using BDAM. A data set is 
cataloged when its fully qualified name and volume identification are entered in 
the SYSCTLG data set. The program catalogs a data set by generating an entry, 
containing the data set name and associated volume information, in the index of 
the catalog. A valid TTR pointer is not placed in the DSCB until the first time the 
data set is referenced. 



The catalog function is used to catalog a non-VSAM data set that was not 
cataloged when it was created. 
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IEHPROGM uncatalogs a non-VSAM data set by removing the data set name and 
associated volume information from the catalog. 

Maintaining Data Set Passwords 

IEHPROGM can be used to maintain password entries in the PASSWORD data set 
and to alter the protection status of direct access data sets in the data set control 
block (DSCB). For a complete description of data set passwords and the 
PASSWORD data set, see OS/VS Data Management for System Programmers, 
GC28-0631, and OS/VS Data Management Services Guide, GC26-3783. 

A data set can have one of three types of password protection, as indicated in 
the DSCB for direct access data sets and in the tape label for tape data sets. The 
possible types of data set password protection are: 

• No protection, which means that no passwords are required to read or write 
the data set. 

• Read/write protection, which means that a password is required to read or 
write the data set. 

• Read- without-pass word protection, which means that a password is required 
only to write the data set; the data set can be read without a password. 

Note: If a system data set is password protected and a problem occurs on the 
data set, maintenance personnel must be provided with the password in order to 
access the data set and resolve the problem. 

A data set can have one or more passwords assigned to it; each password has an 
entry in the PASSWORD data set. A password assigned to a data set can allow 
read and write access or only read access to the data set. 

Figure 23-1 shows the relationship between the protection status of data set ABC 
and the type of access allowed by the passwords assigned to the data set. 
Passwords ABLE and BAKER are assigned to data set ABC. If no password 
protection is set in the DSCB or tape label, data set ABC can be read or written 
without a password. If read/write protection is set in the DSCB or tape label, 
data set ABC can be read with either password ABLE or BAKER and can be 
written with password ABLE. If read-without-password protection is set in the 
DSCB or tape label, data set ABC can be read without a password and can be 
written with password ABLE; password BAKER is never needed. 
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Figure 23-1. Relationship Between the Protection Status of a Data Set and Its 
Passwords 

Before iehprogm is used to maintain data set passwords, the password data 
set must reside on the system residence volume. IEHPROGM can then be used to: 

• Add an entry to the PASSWORD data set. 

• Replace an entry in the PASSWORD data set. 

• Delete an entry from the PASSWORD data set. 

• Provide a list of information from an entry in the PASSWORD data set. 

Each entry in the PASSWORD data set contains the name of the protected data 
set, the password, the protection mode of the password, an access counter, and 
77 bytes of optional user data. The protection mode of the password defines the 
type of access allowed by the password and whether the password is a control 
password or secondary password. The initial password, added to the PASSWORD 
data set for a particular data set, is marked in the entry as the control password 
for that data set. The second and subsequent passwords added for the same data 
set are marked as secondary passwords. 

For direct access data sets, IEHPROGM updates the protection status in the DSCB 
when a control password entry is added, replaced, or deleted. This permits setting 
and resetting the protection status of an existing direct access data set at the 
same time its passwords are added, replaced, or deleted. IEHPROGM automatically 
alters the protection status of a data set in the DSCB if the following conditions 
are met: 

• The control password for the data set is being added, replaced, or deleted. 

• The data set is online. 

• The volume on which the data set resides is specified on the utility control 
statement, or the data set is cataloged. 

• The data set is not allocated within the IEHPROGM job. 

For tape data sets, IEHPROGM cannot update the protection status in the tape 
label when a password entry is added, replaced, or deleted. Protection status in a 
tape label must be set with JCL. 

Passwords to be added, replaced, deleted, or listed can be specified on utility 
control statements or can be entered by the console operator. IEHPROGM issues a 
message to the console operator when a password on a utility control statement 
is either missing or invalid. The message contains the job name, step name, and 
utility control statement name and identifies the particular password that is 
missing or invalid. Two invalid passwords are allowed per password entry on 
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each utility control statement before the request is ignored; a total of five invalid 
passwords is allowed for the password entries on all the utility control statements 
in a job step before the step is canceled. 

Adding Data Set Passwords 

When a password is added for a data set, an entry is created in the PASSWORD 
data set with the specified data set name, password name, protection mode of the 
password (read/ write or read only), and the optional 77 characters of 
user-supplied data. The access counter in the entry is set to zero. 

The control password for a data set must always be specified to add, replace, or 
delete secondary passwords. The control password should not be specified, 
however, to list information from a secondary password entry. 

Secondary passwords can be assigned to a data set to restrict some users to 
reading the data set or to record the number of times certain users access the 
data set. The access counter in each password entry provides a count of the 
number of times the password was used to successfully open the data set. 

If a control password for a direct access, online data set is added, the protection 
status of the data set (read/write or read-without-password) is set in the DSCB. 
However, the data set to be protected must not be allocated within the same job 
as the one in which IEHPROGM is executed. If it is allocated, the DSCB cannot be 
accessed and the protection status is not set. If the data set to be protected is 
being created within the same job, use JCL to set the protection status in the 
DSCB. 

Replacing Data Set Passwords 

Any of the following information may be replaced in a password entry: the 
password, protection mode (read/write or read only) of the password, and the 77 
characters of user data. The access counter of the password entry is set to zero 
when any information in the entry is replaced. The protection status of a data set 
can be changed by replacing the control entry for the data set. 

If the control entry of a direct access, online data set is replaced, the DSCB is 
also reset to indicate any change in the protection status of the data set. 
Therefore, the user should ensure that the volume is online when changing the 
protection status of a direct access data set. 

Deleting Data Set Passwords 

When a control password entry is deleted from the PASSWORD data set, all 
secondary password entries for that data set are also deleted. However, when a 
secondary entry is deleted, no other password entries are deleted. 

If the control password entry is deleted for an online, direct access data set, the 
protection status of the data set in the DSCB is also changed to indicate no 
protection. When deleting a control password for a direct access data set, the 
user should ensure that the volume is online. If the volume is not online, the 
password entry is removed, but data set protection is still indicated in the DSCB; 
the data set cannot be accessed unless another password is added for that data 
set. 

If the control password entry is deleted for a tape data set, the user must change 
the protection status in the tape label to indicate no protection; otherwise, the 
data set cannot be accessed. The tape label may be changed using the iehinitt 
utility program. 

The delete function should be used to delete all the password entries for a 
scratched data set to make the space available for new entries. 
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Listing Password Entries 



Input and Output 



Control 



A list of information from any entry in the PASSWORD data set can be obtained 
in the SYSPRINT data set by providing the password for that entry. The list 
includes: the number of times the password has been used to successfully open 
the data set; the type of password (control password or secondary password) and 
type of access allowed by the password (read/ write or read-only); and the user 
data in the entry. Figure 23-2 shows a sample list of information printed from a 
password entry. 

DECIMAL ACCESS COUNT= 000025 

PROTECT MODE BYTE= SECONDARY, READ ONLY 

USER DATA FIELD= ASSIGNED TO J. BROWN 

Figure 23-2. Listing of a Password Entry 



iehprogm uses as input a control data set that contains utility control 
statements used to control the functions of the program and to indicate those; 
data sets or volumes that are to be modified. 

IEHPROGM produces as output a modified object data set or volume(s), and a 
message data set that contains error messages and information from the 
password data set. 

IEHPROGM provides a return code to indicate the results of program execution. 
The return codes and their meanings are: 

• 00, which indicates successful completion. 

• 04, which indicates that a syntax error was found in the name field of the 
control statement or in the parm field in the EXEC statement. Processing is 
continued. 

• 08, which indicates that a request for a specific operation was ignored because 
of an invalid control statement or an otherwise invalid request. The operation 
is not performed. 

• 12, which indicates that an input/output error was detected when trying to 
read from or write to SYSPRINT, sysin or the VTOC. 

• 16, which indicates an unrecoverable error. The job step is terminated. 



IEHPROGM is controlled by job control statements and utility control statements. 
Job control statements are used to: 

• Execute or invoke the program. 

• Define the control data set. 

• Define volumes and/or devices to be used during the course of program 
execution. 

• Prevent data sets from being deleted inadvertently. 

• Prevent volumes from being demounted before they have been completely 
processed by the program. 

• Suppress listing of utility control statements. 

Utility control statements are used to control the functions of the program and to 
define those data sets or volumes that are to be ; modified. 
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Job Control Statements 



Restrictions 



Table 23-1 shows the job control statements necessary for using IEHPROGM. 

Table 23-1. iehprogm Job Control Statements 

Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (PGM=IEHPROGM) or, if the job control 

statements reside in a procedure library, the procedure name. Additional 
parm information can be specified to control the number of lines per page 
on the output listing and to suppress printing of utility control statements. 
See "PARM Information on the EXEC Statement" below. 

SYSPRINT DD Defines a sequential message data set. 

anynamel DD Defines a permanently mounted volume. (The system residence volume is 
considered to be a permanently mounted volume.) 

anyname2 DD Defines a mountable device type. 

SYSIN DD Defines the control data set. The control data set normally follows the job 

control statements in the input stream; however, it can be defined as a 
member of a procedure library. 

The anynamel DD statement can be entered: 

//anynamel DD UN7T=xxxx,VOLUME=SER=xxxxxx,DISP=OLD 

The UNIT and VOLUME parameters define the device type and volume serial 
number. The DlSP=OLD specification prevents the inadvertent deletion of a data 
set. The anynamel DD statement is arbitrarily assigned the ddname DDl in the 
IEHPROGM examples. 

The anyname2 DD statement can be coded in the following ways: 

//anyname2 DD VOLUME=SER=xxxxxx,UNIT=xxxx,DISP=OLD 

//anyname2 DD VOLUME=(PRIVATE,SER=xxxxxx), 
// UNIT=(xxxx„DEFER),DISP=OLD 

The second example can be used to specify deferred mounting when a large 
number of magnetic tapes or direct access volumes are to be processed in one 
application of the program. The anyname2 DD statement is arbitrarily assigned 
the ddname DD2 in the IEHPROGM examples. DD statements defining additional 
mountable devices are assigned names DD3, DD4, etc. 

Refer to "Appendix C: DD Statements for Defining Mountable Devices" for 
instructions on defining mountable volumes. 



The block size for the SYSPRINT (message) data set must be a multiple of 
121. The block size for the SYSIN (control) data set must be a multiple of 80. 
Any blocking factor can be specified for these block sizes. 

With the exception of the SYSIN and SYSPRINT DD statements, all DD 
statements in Table 23-1 are used as device allocation statements, rather than 
as true data definition statements. Because IEHPROGM modifies the internal 
control blocks created by device allocation DD statements, these statements 
must not include the DSNAME parameter. (All data sets are defined explicitly 
or implicitly by utility control statements.) 

One anynamel DD statement must be included for each permanently mounted 
volume referred to in the job step. 

One anyname2 DD statement must be included for each mountable device to 
be used in the job step. 
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• When IEHPROGM is dynamically invoked in a job step containing a program 
other than IEHPROGM, the DD statements defining mountable devices for 
IEHPROGM must be included in the job stream prior to DD statements defining 
data sets required by the other program. 

• DD statements defining mountable devices must appear in the same order in 
the input stream as the utility control statements that refer to volumes 
mounted on those devices. 

PARM Information on the EXEC Statement 

Additional information can be specified in the PARM parameter of the EXEC 
statement to control the number of lines per page on the output listing and to 
suppress printing of utility control statements. The EXEC statement can be coded: 

// EXEC PGM=IEHPROGM[,PARM='LINECNT=xx, { PRINT } 

{NOPRINT}'] 

The LINECNT parameter specifies the number of lines per page in the listing of 
the SYSPRINT data set; xx is a 2-digit number, from 01 through 99. If LINECNT 
is omitted, or if an error is encountered in the LINECNT subparameter, the 
number of lines per page will be 45. 

The PRINT value specifies that the utility control statements are to be written to 
the SYSPRINT data set. If neither PRINT nor NOPRINT is coded, PRINT is 
assumed. 

The NOPRINT value specifies that utility control statements are not to be written 
to the SYSPRINT data set. Suppressing printing of utility control statements 
assures that passwords assigned to data sets remain confidential. However, 
suppressing printing may make it difficult to interpret error messages because the 
relevant utility control statement is not printed before the message. 

Utility Control Statements 

IEHPROGM is controlled by the following utility control statements: 

• SCRATCH statement, which is used to scratch a data set or a member from a 
direct access volume. 

• RENAME statement, which is used to change the name or alias of a data set or 
member residing on a direct access volume. 

• CATLG statement, which is used to generate an entry in the index of a catalog. 

• UNCATLG statement, which is used to remove an entry from the index of the 
catalog. 

• ADD statement, which is used to add a password entry in the PASSWORD data 
set. 

• REPLACE statement, which is used to replace information in a password entry. 

• DELETEP statement, which is used to delete an entry in the PASSWORD data 
set. 

• LIST statement, which is used to format and list information from a password 
entry. 



SCRATCH Statement 



The SCRATCH statement is used to scratch a data set or member from a direct 
access volume. A data set or member is scratched only from the volumes 
designated in the SCRATCH statement. This function does not uncatalog 
scratched data sets. 
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The format of the SCRATCH statement is: 



RENAME Statement 



[label] SCRATCH 



{DSNAME=name} 
{VTOC} 

,VOL=cteWce=//sf 

[,PURGE] 

[,MEMBER= name] 
[,SYS] 



where: 



DSNAME=name 

specifies the fully qualified name of either the data set to be scratched or the 
partitioned data set that contains the member to be scratched. 

VTOC 

specifies that all data sets on the specified volume, except those protected by a 
password or those whose expiration dates have not expired, are to be 
scratched. Password-protected data sets are scratched if the correct password 
is provided. The effect of VTOC is modified when it is used with PURGE or 
SYS. 

VOL = device= list 

specifies the volume or volumes that contain the data set or sets to be 
scratched. If VTOC is specified, VOL cannot specify more than one volume. 
Caution should be used when specifying VTOC if VOL specifies the system 
residence volume. The list must not contain more than 50 volumes in any 
other case. 

PURGE 

specifies that each data set specified by DSNAME or VTOC be scratched, even if 
its expiration date has not elapsed. If PURGE is omitted, the specified data sets 
are scratched only if their expiration dates have elapsed. 

MEMBER==name 

specifies a member name or alias of a member to be removed from the 
directory of a partitioned data set. If MEMBER is omitted, the entire data set 
or volume of data sets is scratched. 

SYS 

specifies that data sets that are to be scratched have names that begin with 
"AAAAAAAA.AAAAAAAA.AAAAAAAA.AAAAAAAA." or "SYSnnnnn.T" and "F," 
"V" or "A" in position 19. These are names assigned to data sets by the 
operating system. This parameter is valid only when VTOC is specified. 

If the name of the data set to be scratched begins with SYS, nnnnn is the date. 

When executing a SCRATCH operation, care should be taken to ensure that the 
data set or volume is not being used by a program executing concurrently. 



The RENAME statement is used to change the true name or alias of a data set or 
member residing on a direct access volume. The name is changed only on the 
designated volume(s). The rename operation does not update the catalog. 

The format of the RENAME statement is: 



[label] RENAME 



DSNAME=name 
,VOL=cteWce=tfst 
,NEWNAME=name 
[,MEMBER=name] 
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CATLG Statement 



where: 

DSNAME=name 

specifies the fully qualified name of the data set to be renamed or specifies the 
data set that contains the member to be renamed. 

VOL=dew"ce= list 

specifies the volume or volumes that contain the data set or member whose 
name is to be changed. If MEMBER is specified, VOL cannot specify more than 
one volume. The list must not contain more than 50 volumes in any other 
case. 

NEWNAME=name 

specifies the new fully qualified name for the data set, or the new member or 
alias. 

MEMBER = name 

specifies the name or alias for a member (in the named data set) that is to be 
renamed. If member is omitted, the specified data set name is changed. 



The CATLG statement is used to generate a non-VSAM entry in the index of a 
catalog. When cataloging generation and VSAM data sets, refer to OS/VS Access 
Method Services, GC35-0009. 

The format of the CATLG statement is: 

[label] CATLG DSNAME=name 
,VOL=deWce=//st 

where: 

DSNAME=name 

specifies the fully qualified name of the data set to be cataloged. The qualified 
name must not exceed 44 characters, including delimiters. 

VOL=deWce=//'sf 

specifies the volume or volumes that contain the data set to be cataloged. For 
either a sequential data set or an indexed sequential data set, the volume serial 
numbers must appear in the same order in which they were originally 
encountered (in DD statements within the input stream) when the data set was 
created. All serial numbers specified in VOL must represent the same device 
type. The list must not contain more than 50 volumes. 

Notes: When device is represented by a group name (for example, SYSDA) instead 
of a generic name (for example, 2314 or 2400) in the VOL parameter, the catalog 
operation does not enter the device type code in the system catalog. Instead, it 
places a unique entry in the device type field of the catalog. The allocation of the 
device for this entry may not be satisfactory to the user. The generic name 
should be used if the group name was generated for one or more device types. 
When the system is subsequently generated, this entry may no longer be valid; 
that is, all such group name entries should be uncataloged and then recataloged 
after a subsequent generation of the system. 
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UINICATLG Statement 



When cataloging data sets residing on tape, specify the data set sequence number 
and the volume serial number, as follows: 

VOL=device=({serial,seqno},...) 

If a data set is created on a 9-track dual density tape unit (2400-4), the data set 
can be cataloged with a device specification of 2400 for an 800 bits per inch 
tape or 2400-3 for a 1600 bits per inch tape. If a device specification of 2400-4 
is made when the data set is cataloged, any subsequent retrieval of that data set 
is made on a dual density unit. 

Note: The CVOL keyword described in previous OS/VS releases is ignored in VS2 
Release 2. No return code or message is issued acknowledging this. 

The UNCATLG statement is used to remove a non-VSAM entry from the index of 
the catalog. 

The format of the UNCATLG statement is: 

[label] UNCATLG DSNAME=name 

where: 

DSNAME=: name 

specifies the fully qualified name of the data set to be uncataloged. 

Note: The CVOL keyword described in previous OS/VS releases is ignored in VS2 
Release 2. No return code or message is issued acknowledging this. 

ADD (Add a Password) Statement 

The add statement is used to add a password entry in the PASSWORD data set. 
When the control entry for a direct access, online data set is added, the indicated 
protection status of the data set is set in the DSCB; when a secondary entry is 
added, the protection status in the DSCB is not changed. 

The format of the ADD statement is: 

[label] ADD DSNAME=name 

[,PASWORD2=new-password] 
[,CPASWORD = control-password] 
[,TYPE=code] 
[,VOL=deWce=//st] 
[,DATA= 'user-data'] 

where: 

DSNAME= name 

specifies the fully qualified name of the data set to which the password is to 
be assigned. 

PASWORD2= new -password 

specifies the password to be added. The password can consist of one- to 
eight-alphameric characters. If PASWORD2 is omitted, the operator is prompted 
for a new password. 

CPASWORD = control-password 

specifies the control password for the data set. The control password must be 
specified unless this is the first password assigned to the data set. 
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TYPE=code 

specifies the protection code of the password and, if a control password is 
being assigned to a direct access, online data set, specifies the protection 
status of the data set. If this parameter is omitted, the new password is 
assigned the same protection code as the control password for the data set. If 
a control password is being added, type=3 is the default. The values that can 
be specified for code are: 

1 

specifies that the password is to allow both read and write access to the 
data set; if a control password is being assigned, read/write protection is 
set in the DSCB. 

2 

specifies that the password is to allow only read access to the data set; if a 
control password is being assigned, read/write protection is set in the DSCB. 

3 

specifies that the password is to allow both read and write access to the 
data set; if a control password is being assigned, read-without-password 
protection is set in the DSCB. 

VOL=dev/ce= list 

specifies the direct access volume or volumes that contain the data set to be 
protected. If omitted, the protection status of the data set is not set in the 
DSCB, unless the data set is cataloged. This parameter is not necessary for 
secondary password entries or if the desired protection status is already set in 
the DSCB. The list must not contain more than 50 volumes. 

DATA= 'user-data' 

specifies that user data is to be included in the password entry. The user data 
must be in single quotes and must not exceed 77 characters. 

REPLACE (Replace a Password) Statement 

The replace statement is used to replace any or all of the following information 
in a password entry: the password name, protection mode (read/write or read 
only) of the password, and user data. When the control entry for a direct access, 
online data set is replaced, the protection status of the data set is changed in the 
DSCB if necessary; when a secondary entry is replaced, the protection status in 
the DSCB is not changed. 

The format of the REPLACE statement is: 

[label] REPLACE DSNAME=name 

[,PASWORDl =current~password] 
[,PASWORD2=new-password] 
[,CPASWORD=contro/-password] 
[,TYPE=code] 
[,VOL=deWce=//st] 
[,DATA= 'user-data'] 
where: 

DSNAME= name 

specifies the fully qualified name of the data set whose password entry is to be 
changed. 

PASWORD1 =current-password 

specifies the current password in the entry to be changed. If PASWORDl is 
omitted, the operator is prompted for the current password. 
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PASWORD2 = new- password 

specifies the new password to be assigned to the entry. If the password is not 
to be changed, the current password must also be specified as the new 
password. The password can consist of one- to eight-alphameric characters. If 
PASWORD2 is omitted, the operator is prompted for a new password. 

CPASWORD = control-password 

specifies the control password for the data set whose entry is to be changed. 
The control password must be specified unless the control entry is being 
changed. If the control entry is to be changed, the control password must be 
specified as paswordi. 

TYPE=code 

specifies the protection code of the password and, if a control password entry 
is to be changed for a direct access, online data set, specifies the protection 
status of the data set. If this parameter is omitted, the protection is not 
changed. The values that can be specified for code are: 

1 

specifies that the password is to allow both read and write access to the 
data set; if a control password is being changed, read/ write protection is set 
in the DSCB. 

2 

specifies that the password is to allow only read access to the data set; if a 
control password is being changed, read/ write protection is set in the DSCB. 

3 

specifies that the password is to allow both read and write access to the 
data set; if a control password is being changed, read- without-pass word 
protection is set in the DSCB. 

VOL=dev/ce= list 

specifies the direct access volume or volumes that contain the data set whose 
protection status is to be changed. If omitted, the protection status of the data 
set is not changed in the DSCB, unless the data set is cataloged. This 
parameter is not necessary for secondary password entries or if the protection 
status of the data set is not to be changed. The list must not contain more 
than 50 volumes. 

DATA= 'user-data' 

specifies that user data is to be included in the password entry. The user data 
must be in single quotes and must not exceed 77 characters. If this parameter 
is omitted, the user data is not changed. 

DELETEiP (Delete a Password) Statement 

The DELETEP statement is used to delete an entry in the PASSWORD data set. If 
a control entry is deleted, all the secondary entries for that data set are also 
deleted. If a secondary entry is deleted, only that entry is deleted. When the 
control entry for a direct access, online data set is deleted, the protection status 
in the DSCB is set to indicate that the data set is no longer protected. 

The format of the DELETEP statement is: 

[label] DELETEP DSNAME= name 

[,PASWORDl =current-password] 
[,CPASWORD=contro/-password] 
[,VOL=dew'ce=//st] 
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where: 

DSNAME= name 

specifies the fully qualified name of the data set whose password is to be 
deleted. 

PASWORD1 =current-password 

specifies the password to be deleted. 

CPASWORD = control-password 

specifies the control password for the data set whose password is to be 
deleted. The control password must be specified unless the control password is 
to be deleted. If the control password is to be deleted, the control password 
must be specified as PASWORD1. 

VOL=dev/ce=//st 

specifies the direct access volume or volumes that contain the data set whose 
password is to be deleted. If omitted, the protection status of the data set is 
not changed in the DSCB, unless the data set is cataloged. This parameter is 
not necessary if a secondary password is to be deleted. 

LIST (List Information from a Password) Statement 

The LIST statement is used to format and print information from a password 
entry. 

The format of the LIST statement is: 

[label] LIST DSNAME=name 

,PASWORDl =current-password 

where: 

DSNAME= name 

specifies the fully qualified name of the data set whose password entry is to be 
listed. 

PASWORD1 =current-password 

specifies the password in the entry to be listed. 



IEHPROGM Examples 



The following examples illustrate some of the uses of IEHPROGM. Table 23-2 can 
be used as a quick reference guide to IEHPROGM examples. The numbers in the 
"Example" column point to the examples that follow. 
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Table 23-2. iehprogm Example Directory 



IEHPROGM Example 1 



IEHPROGM Example 2 



Operation 

SCRATCH 

SCRATCH 
UNCATLG 

RENAME, 

UNCATLG 

CATLG 



UNCATLG 

CATLG 

RENAME, 
DELETEP, 
and ADD 

LIST and 
REPLACE 

RENAME 



Mountable 
Volumes 

2314 Disk 

2314 Disk 

2314 Disks 



2314 Disk 
2314 Disk 
2314 Disk 



Comments 

vtoc is to be scratched. 

Two data sets are to be scratched and 
uncataloged. 

A data set is to be renamed on two mountable 

devices; the old data set name is to 

be removed from the catalog. The 

data set is cataloged under its new name. 

Object data set resides on two mountable 

devices. 

Three data sets are to be uncataloged. 

Catalog data sets on a volume. 

The object data set exists on one mountable 
device. 



Example 
l 

2 



2314 Disk The object data set exists on two mountable 
devices. 

2314 Disk Rename a member of a partitioned data set, 



In the IEHPROGM examples, the EXEC statement and the SYSPRINT DD statement 
can be replaced with the following job control statement: 

// EXEC PROC=MOD 

which invokes the following IBM-supplied cataloged procedure: 

//MOD EXEC PGM=IEHPROGM,REGION=44K 
//DDSRV DD VOLUME=REF=SYSl.SVCLIB,DISP=OLD 
//SYSPRINT DD SYSOUT=A 

Note: In the IEHPROGM examples, the DDl DD statement always refers to the 
system residence volume. 



In the following example, data sets are to be scratched from the volume table of 
contents of a mountable volume. Because the system residence volume is not 
referred to, no DDl DD statement is necessary in the job stream. 

The example follows: 

//SCRVTOC JOB 09#550, BROWN 
// EXEC PGM= IEHPROGM 

//SYSPRINT DD SYSOUT=A 



UNIT=23 1 4 , VOLUME=SER=23 1 400 , DISP=OLD 
VTOC , VOL=23 1 4=231 400 



//DD2 DD 
//SYSIN DD 
SCRATCH 
/* 

The SCRATCH statement, used in this example, indicates that all data sets 
(including those beginning with AAAAAA.AAAAAA.AAAAAA.AAAAAA) whose 
expiration dates have expired are to be scratched from the specified volume. 



In this example, two data sets are to be scratched: SETl is to be scratched on 
volume 231400, and a.b.c.d.e is to be scratched on volume 231400. Both data 
sets are to be uncataloged. Because the system residence volume, which resides 
on a 3330 volume, is referred to through use of the UNCATLG statements, a DD 
statement is included in the input stream. 
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IEHPROGM Example 3 



IEHPROGM Example 4 



The example follows: 

//SCRDSETS JOB 09#550, BROWN 

// EXEC PGM=IEHPROGM 

//SYSPRINT DD SYSOUT=A 

//DD1 DD UNIT=3330,VOLUME=SER=1 1 1 1 1 1 ,DISP=OLD 

//DD2 DD UNIT=2314,DISP=OLD,VOLUME=SER=231400 

//SYSIN DD * 

SCRATCH DSNAME=SET1 , VOL=23 1 4=23 1 400 

UNCATLG DSNAME=SET1 

SCRATCH DSNAME=A . B . C . D . E , VOL=2 3 1 4=23 1400 

UNCATLG DSNAME=A . B . C . D . E 
/* 

The control statements are discussed below: 

• The first SCRATCH statement specifies that SETl, which resides on volume 
231400, is to be scratched. 

• The first UNCATLG statement specifies that SETl is to be uncataloged. 

• The second SCRATCH statement specifies that A.B.C.D.E, which resides on 
volume 231400, is to be scratched. 

• The second UNCATLG statement specifies that A.B.C.D.E is to be uncataloged. 



In this example, the name of a data set is to be changed on two mountable 
volumes. The old data set name is to be removed from the catalog and the data 
set is to be cataloged under its new data set name. 

The example follows: 

72 
//RENAMEDS JOB 09#550, BROWN 
// EXEC PGM= IEHPROGM 

//SYSPRINT DD SYSOUT=A 

//DD1 DD VOLUME=SER=1 1 1 1 1 1 , UNIT=3330, DISP=OLD 

//DD2 DD UNIT=( 2314, , DEFER ),DISP=OLD, 

// VOLUME=( PRIVATE, SER=( 231400,231401 ) ) 
//SYSIN DD * 

RENAME DSNAME=A . B . C , NEWNAME=NEWSET , C 

VOL=2314=( 231400,231401 ) 
UNCATLG DSNAME=A . B . C 

CATLG DSNAME=NEWSET,VOL=2314=( 231400,231401 ) 
/* 

The control statements are discussed below: 

• RENAME specifies that data set A.B.C, which resides on volumes 231400 and 
231401, is to be renamed NEWSET. 

• UNCATLG specifies that data set A.B.C is to be uncataloged. 

• CATLG specifies that NEWSET, which resides on volumes 231400 and 231401, 
is to be cataloged. 



In this example, three data sets — A.B.C.D.E.F.SETi, A.B.C.G.H.SET2, and 
A.B.I.J.K.SET3 — are to be uncataloged. The system residence volume resides on a 
2314 volume. 
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The example follows: 



IEHPROGM Example 5 



//DLTSTRUC JOB 


09#550, BROWN 




// EXEC 


PGM=IEHPROGM 




//SYSPRINT DD 


SYSOUT=A 




//DD1 DD 


UNIT=2314,VOLUME= 


=SER=1 11111 ,DISP==OLD 


//SYSIN DD 


* 




UNCATLG 


DSNAME=A.B.C.D.E. 


.F.SET1 


UNGATLG 


DSNAME=A.B.C.G.H. 


.SET2 


UNCATLG 


DSNAME=A.B.I.J.K. 


.SET3 


/* 







The control statements are discussed below: 

• The UNCATLG statements specify that data sets A.B.C.D.E.F.SETl, 
A.B.C.G.H.SET2, and A.B.U.K.SET3 are to be uncataloged. 



In this example, three data sets are to be cataloged. The system residence volume 
is a 3330. 

The example follows: 

//CATALOG JOB 09#550, BROWN 



// 



EXEC PGM= IEHPROGM 



//SYSPRINT DD 



//DD1 

//DD2 

//SYSIN 

CATLG 
CATLG 
CATLG 

/* 



SYSOUT=A 

DD UNIT=3330,VOLUME=SER=1 11111 ,DISP=OLD 
DD UNIT=23 1 4 , VOLUME=SER=23 1 400 , DISP=OLD 
DD * 

DSNAME=X . BB . CCC , VOL=23 1 4=23 1 401 

DSNAME=Y . BB . CC , VOL=23 1 4=23 1 40 1 

DSNAME=Z . BB . XT , VOL=2 3 1 4=23 1 40 1 



The control statements are discussed below: 

• The CATLG statements catalog three data sets (X.BB.CCC, Y.BB.CC, and 

Z.BB.XT). 
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In this example, a data set is to be renamed. The data set passwords assigned to 
the old data set name are to be deleted. Then two passwords are to be assigned 
to the new data set name. 

Note: If the data set is not cataloged, a message indicating that the LOCATE 
macro instruction failed is issued. The return code is 8. 



The example follows: 



//ADDP AS S JOB 09#550, BROWN 

EXEC PGM=IEHPROGM,PARM='NOPRINT' 
//SYSPRINT DD SYSOUT=A 

//DD1 DD VOLUME=( PRIVATE, SER=23 1400 ) ,DISP=OLD, 

// UNIT=( 2314, , DEFER) 
//SYSIN DD * 

RENAME DSNAME=OLD , VOL=23 1 4=23 1 400 , NEWNAME=NEW 
DELETEP DSNAME=OLD , PASWORD 1 =KEY 

ADD DSNAME=NEW,PASWORD2=KEY,TYPE=1 , 

DAT A= ' SECONDARY IS READ 1 
ADD DSNAME=NEW , PASWORD2=READ , CPASWORD=KEY , TYPE=2 , 
DAT A=' AS SIGNED TO J. DOE' 
/* 



72 
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IEHPROGM Example 7 



IEHPROGM Example 8 



The control statements are discussed below: 

• DELETEP specifies that the entry for the password KEY is to be deleted. 
Because KEY is a control password in this example, all the password entries 
for the data set name are deleted. The VOL parameter is not needed because 
the protection status of the data set as set in the DSCB is not to be changed; 
read/write protection is presently set in the DSCB, and read/write protection is 
desired when the passwords are reassigned under the new data set name. 

• The ADD statements specify that entries are to be added for passwords key 
and read, key becomes the control password and allows both read and write 
access to the data set. read becomes a secondary password and allows only 
read access to the data set. The vol parameter is not needed, because the 
protection status of the data set is still set in the DSCB. 

Note: The operator is required to supply a password to rename the old data set. 



In this example, information from a password entry is to be listed. Then the 
protection mode of the password, the protection status of the data set, and the 
user data are to be changed. 



The example follows: 



72 



//REPLPASS JOB 

EXEC 
//SYSPRINT DD 
//DD1 DD 
//DD2 DD 
// UNIT=( 2314, , DEFER ),DISP=OLD 
//SYSIN DD * 



09#550, BROWN 

PGM=IEHPROGM, PARM= ' NOPRINT ' 

SYSOUT=A 

UNIT=3330,VOLUME=SER=1 11111 ,DISP=OLD 

VOLUME=( PRIVATE , SER=( 231 400 ,231401 ) ) , 



/* 



LIST DSNAME=A.B.C,PASWORD1=ABLE 
REPLACE DSNAME=A . B . C , PASWORD 1 =ABLE , 
PASWORD2=ABLE , TYPE=3 , 
VOL=2314=( 231400,231401 ), 
DATA='NO SECONDARIES; ASSIGNED TO DEPT 31 



The control statements are discussed below: 

• LIST specifies that the access counter, protection mode, and user data from the 
entry for password able are to be listed. Listing the entry permits the 
content of the access counter to be recorded before the counter is reset to 
zero by the REPLACE statement. 

• REPLACE specifies that the protection mode of password ABLE is to be 
changed to allow both read and write access and that the protection status of 
the data set is to be changed to write-only protection. The VOL parameter is 
required because the protection status of the data set is being changed and the 
data set, in this example, is not cataloged. Because this is a control password, 
the CPASWORD parameter is not required. 



In this example, a member of a partitioned data set is to be renamed. 
The example follows: 

//REN JOB 09#550, BROWN 

// EXEC PGM= IEHPROGM 

//DD1 DD VOL=SER=23141 1 ,DISP=OLD,UNIT=2314 

//SYSIN DD * 

RENAME VOL=23 14=23 141 1 ,DSNAME=DATASET,NEWNAME=BC,MEMBER=ABC 
/* 
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The control statements are discussed below: 

• DDl dd defines a permanently mounted volume. 

• SYSIN DD defines the input data set, which immediately follows in the input 
stream. 

• RENAME specifies that member ABC in the partitioned data set DATASET, 
which resides on a 2314 volume, is to be renamed BC. 
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IEHUCAT Program (VS1 Only) 



Input and Output 



IEHUCAT is a system utility program used to update an OS catalog to the level of 
the OS/VS2 Release 2 catalog. (See "Introduction" for general system utility 
information.) 

IEHUCAT enables a user of VS2 Release 2 to temporarily move back to a system 
(OS/mft, os/mvt, os/vsi, or OS/VS2 Release 1) that uses the OS catalogs. His 
non-VSAM data sets, on the OS catalog, are made equivalent to those same data 
sets on his VSAM catalog, provided: 

• IEHUCAT is installed (in SYS1.LINKLIB or a private JOBLIB) on an MFT, MVT, 
VSl, or VS2 Release 1 system. 

• The OS catalog used when the conversion to VS2 Release 2 was made is 
available. 

• The SMF option to record type 63 and type 67 records was selected at IPL time 
and the SMF data set (SYSl.MANX/SYSl.MANY) was retained. (For detailed 
information on SMF record types 63 and 67, see OS/VS Virtual Storage Access 
Method (VSAM) System Information, GC26-3835.) 

• All related CVOLs are mounted when more than one catalog is being updated. 

When moving VSAM catalogs between VS2 Release 2 and other systems, it is 
recommended that they contain only VSAM data set entries. 



Input to the IEHUCAT program is the SMF data set containing the SMF type 63 or 
67 records produced by VS2 Release 2 catalog management activity. 

IEHUCAT output consists of the updated entries in the catalog, the SMF input 
entry, and any error messages. 
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Output Listing 



Figure 24-1 is a sample of the IEHUCAT output listing. 



SYS 



TIME 



DATE JOBNAME USERID VS/2RELEASE 2 

CATALOG NAME 
AMASTCAT 



OS DATASET NAME 



VS2 01:26:58 13.038 DEFIN BRWN AMASTCAT VRT 1 . NONVSA . DS 

IEH014I VRT 1 .NONVSA. DS RECATALOG REQUEST HAS FAILED. DATA SET HAS BEEN CATALOGED 
VOLUME LIST 230300 231400 232123 



RUN STATISTICS: 

ENTRIES CATALOGED UNCATALOGED RECATALOGED 

TOTALS 1 ■ 

END OF JOB. HIGHEST RETURN CODE WAS 0. 

Explanation: 

SYS 

TIME 

DATE 

JOBNAME 

USERID 



NOT FOUND RECORDS READ 
15 



Identification of the job that updated or created the VS2 
Release 2 catalog entry for the OS data set identified under 

"OS DATASET NAME." 



VS/2 Release 
CATALOG NAME 

OS DATASET NAME 



IEH014I 
VOLUME LIST 

RUN STATISTICS 



The name assigned to the VS2 Release 2 master catalog. 

The non-VSAM data set whose catalog entry has been the 
target of VS2 Release 2 catalog management activity. 

Message associated with IEHUCAT processing. 

The volume serial numbers of the volumes containing the 
data set named under the OS DATASET NAME heading. 

Summary of IEHUCAT processing: ERRORS indicates the 
number of catalog, uncatalog, and recatalog operations that 
failed. The return code noted is the highest return code 
issued by the catalog or INDEX macro instructions used 
by iehucat. RECORDS READ indicates the total number 
of records encountered in the SMF data set. 



Figure 24-1. IEHUCAT Output Listing 



Control 



Execution of IEHUCAT can be requested through job control statements or 
through LINK or ATTACH macro instructions issued by a problem program. (See 
Appendix B of this publication for LINK or ATTACH usage.) 

There are no IEHUCAT utility control statements. Program control is exercised 
through the PARM= field of the EXEC job control statement or the PARAM= 
operand of LINK or ATTACH. The program control available is: 

CVOL(volser,device type): update SYSCTLG on this CVOL only. 

NOLIST: list only error messages. 

LIST: list all program output (default value). 



Job Control Statements 



Table 24-1 shows the job control statements applicable to use of IEHUCAT. 

Table 24-1. IEHUCAT Job Control Statements 

Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (pgm=iehucat) and program controls in the 

PARM- field. 

anyname DE) Optional. A series of these DD statements will force the mounting of CVOLS 

(other than the system residence volume) containing the SYSCTLG data set 
and avoid failure of catalog requests. By supplying a DD statement for each 
CVOL connected to the system residence volume, the volumes will be 
allocated and mounted during job initiation. 

SYSUT1 DD Defines the SMF data set. 

SYSPRINT DD Defines a sequential data set for IEHUCAT output listing. 
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IEHUCAT Examples 



The following examples illustrate IEHUCAT usage. Table 24-2 can be used as a 
quick reference guide to IEHUCAT examples. The numbers in the "Example" 
column point to the examples that follow. 



Table 24-2. IEHUCAT 


Example Directory 




Operation 


Comment 


Example 


Update sysctlg on 
sysres cvol and any 
other mounted CVOLs 


Full Listing 


1 


Update sysctlg on 
sysres cvol and ensure 
mounting of specific 
CVOLs. 


Full Listing 


2 


Update a specific 

CVOL. 


Error messages only 
listed. 


3 



IEHUCAT Example 1 



IEHUCAT Example 2 



In this example, IEHUCAT updates SYSCTLG on the system residence volume and 
any connected CVOLs that are mounted at execution time. 

The example follows: 

//UPDOSCAT JOB 18#550, BROWN 

// EXEC PGM=IEHUCAT 

//SYSUT1 DD DSN=SYS1,.MANY,DISP=SHR,VOL=SER=123123, 

// UNIT=3330 

//SYSPRINT DD SYSOUT=A 

/* 



In this example, IEHUCAT updates SYSCTLG on the system residence volume. It 
also updates the four CVOLs whose mounting is ensured by the DD statements; 
CVOLl through CVOL4. It updates any other connected CVOLS that are mounted 
when IEHUCAT execution takes place. 

The example follows: 

//UPD4CVOL JOB 18# 550, BROWN 

// EXEC PGM=IEHUCAT 

//SYSUT1 DD DSN=SYS1 .MANY, DISP=SHR, VOL=SER=1 231 23 , 

// UNIT=3330 

//CVOL1 DD 

//CVOL2 DD 

//CVOL3 DD 

//CV0L4 DD 

//SYSPRINT DD 

/* 



UNIT=23 1 4 , VOL=SER=CVOL 1 
UNIT=2 3 1 4 , VOL=SER=CVOL2 
UNIT=23 1 4 , VOL=SER=CVOL3 
UNIT=2 3 1 4 , VOL=SER=CVOL4 
SYSOUT=A 



IEHUCAT Example 3 



In this example, IEHUCAT updates SYSCTLG on only the specific CVOL identified 
in the PARM field of the EXEC statement. Only error messages will be listed. 

The. example follows: 

//UPDACVOL JOB 18# 550, BROWN 

// EXEC PGM=IEHUCAT,PARM='NOLIST,CVOL( 123123,2314 )' 

//SYSUT1 DD DSN=SYS1 ,MANY,DISP=SHR, VOL=SER=1 21 121 , 

// UNIT=3330 

//SYSPRINT DD SYSOUT=A 

/* 
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IFHSTATR Program 



IFHSTATR is a system utility used to format and print information from type 21 
(error statistics by volume) records. (See "Introduction" for general system utility 
information.) 

Figure 25-1 shows the format of the type 21 record. 



4 


8ytes of Record Descriptor Word 





System 
Indicatoi 


Record Type 


Time of Day 
Current Date 


4 


Time of Day (continued) 


8 


Current Date 


(continued) 
dentifier 


System 
Identification 


12 


System 


Length oT rest bTrecord 
including this field 


16 


Volume Serial Number 


20 


Volume Serial No (cont.) Channel/Unit Address 


24 


UCB Type 


28 


Temporary Read 
Errors 


Temporary Write 
Errors 


Start l/O's 


32 


Permanent Read 
Errors 


Permanent Write 
Errors 


Noise Blocks 


Erase Gaps 


3b 


Erase Gaps 
(continued) 


Cleaner Actions 


Tape Density 


40 


Block Size 


Reserved 



Figure 25-1. Type 21 (ESV) Record Format 

Error statistics by volume (ESV) records should be retrieved from the IFASMPDP 
tape or from SYS1.MAN (on tape). ESV can also be retrieved directly from 
SYSi.MANX or SYSl.MANY (on a direct access storage device), however, 
IFHSTATR does not clear the SYSI.MANX (or SYSl.MANY) data set or make it 
available for additional records. 



Assessing the Quality of a Tape Library 



The statistics gathered by SMF in Type 21 records can be very useful in assessing 
the quality of a tape library. IFHSTATR prints Type 21 records in the same order 
that they were gathered, that is, date/time sequence. You may find it useful to 
sort Type 21 records into volume serial number sequence, into channel unit 
sequence, and into error occurrence sequence to aid in analyzing the conditioii of 
the library. 

The IFHSTATR report helps to identify deteriorating media (tapes); occasionally 
poor performance from a particular tape drive can also be identified. The 
permanent read error counter or permanent write error counter is incremented by 
one each time the Tape Error Recovery routines (ERPs) determine that the error 
is permanent and is returned to the user with indication of a permanent I/O 
error. If a SYNAD routine to handle such errors is present, the counts in these 
fields can be greater than one. The temporary read error counter and temporary 
write error counter are incremented when the ERP initially handles an error 
condition which is corrected in the ERP. The severity of a temporary error can be 
estimated by analyzing either the erase gap counter for write errors or the noise 
block anc cleaner action counters for read errors. The erase gap counter is 
incremented each time a write error is retried. For example, if the temporary 
write error counter contains 2 and the erase gap counter contains 5, the erp was 
entered twice for write error recovery The average recovery actions were 2.5 per 
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Input and Output 



error (actually may have been 1 and 4). The cleaner action counter is only 
incremented every fourth read retry. A ratio of one cleaner action to one 
temporary read error indicates, in general, recovery on the fifth retry (the first 
retry after the cleaner action). A ratio of ten cleaner actions to one temporary 
error indicates that recovery is, in general, a result of reading the tape in the 
opposite direction (reading backward on a read forward tape or reading forward 
on a read backward tape). The noise block counter is incremented once for each 
noise record (record less than minimum read length) encountered. 

In analyzing IFHSTATR reports, the usage (SIO) count should also be considered, 
because it is the count of all Start I/O's to the tape drive, except those issued by 
the ERP in the course of error recovery. The usage count can be used to 
determine the ratio of error free accesses of the tape to total accesses of the 
tape. 



IFHSTATR uses as input type 21 records, which contain information about errors 
on magnetic tape. IFHSTATR processes only type 21 records; if none are found, a 
message is written to the output data set. 

IFHSTATR produces as output an output data set, which contains information 
selected from type 21 records. The output takes the form of 121 -byte unblocked 
records, with an ASA control character in the first byte of each record. 

Figure 25-2 shows a sample of printed output from IFHSTATR. 




Figure 25-2. Sample Output from ifhstatr 



Control 



IFHSTATR is controlled by job control statements. Utility control statements are 
not used. 



Job Control Statements 



Table 25-1 shows the job control statements necessary for using IFHSTATR. 

Table 25-1. ifhstatr Job Control Statements 

Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (PGM«ifhstatr). 

SYSUT1 DD Defines the input data set and the device on which it resides. The dsname, 
unit, VOLUME, label, DCB, and DISP parameters should be included. 

SYSUT2 DD Defines the sequential data set on which the output is to b e w ritten. 

The output data set can reside on any output device supported by BSAM. 
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IFHSTATR Example 



Note: The lrecl and BLKSIZE parameters are not specified by ifhstatr. This 
information is taken from the dcb parameter on the sysuti DD statement or 
from the tape label. 



This example shows the JCL needed to produce a report. 
The example follows: 

// JOB 

// EXEC PGM=IFHSTATR 

//SYSUT 1 DD UNIT=2400 , DSNAME=SYS 1 . MAN , LABEL=( , SL) , 

// VOLUME=SER=VOLID f DISP=OLD 

//SYSUT2 DD SYSOUT=A 

/* 
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Appendix A: Exit Routine Linkage 



Utility programs can be linked to user-supplied exit routines for additional 
processing. 

Linking to an Exit Routine 

Linking to an exit routine from a utility program is accomplished in one of the 
following ways: 

• If the exit routine is for label processing or totaling, or if the exit routine is 
specified in the IEBTCRIN program by OUTREC or ERROR, linkage is performed 
by the BALR instruction. 

• In all other cases, linkage is performed by using the LINK macro instruction. 

The link macro instruction contains the symbolic name of the entry point of an 
exit routine and, if required, a list of parameters. 

For further information on the use of the link macro instruction, see OS/VS 
Supervisor Services and Macros, GC27-6979, and OS/VS Data Management Macro 
Instructions, GC26-3793. 

At the time of the linkage operation: 

• General register 1 contains the starting address of the parameter list, or 
contains zero to indicate end-of-file on the input data set for the IEBTCRIN 
OUTREC or ERROR exits. 

• General register 13 contains the address of the register save area. This save 
area must not be used by user label processing routines. See "Appendix D: 
Processing User Labels." 

• General register 14 contains the address of the return point in the utility 
program. 

• General register 15 contains the address of the entry point to the exit routine. 

Registers 1 through 14 must be restored before control is returned to the utility 
program. 

The exit routine must be contained in either the job library or the link library. 

The parameter lists passed to label processing routines and parameter lists passed 
to nonlabel processing routines are described in the topics that follow. 

Label Processing Routine Parameters 

The parameters passed to a user's label processing routine are addresses of the 
80-byte label buffer, the DCB being processed, the status information if an 
uncorrectable input/output error occurs, and the totaling area. 

The 80-byte label buffer contains an image of the user label when an input label 
is being processed. When an output label is being processed, the buffer contains 
no significant information at entry to the user's label processing routine. When 
the utility program has been requested to generate labels, the label processing 
routine constructs a label in the label buffer. 
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If standard user labels (SUL) are specified on the DD statement for a data set, but 
the data set has no user labels, the system still takes the specified exits to the 
appropriate user's routine. In such a case, the user's input label processing 
routine is entered with the buffer address parameter set to zero. 

The format and content of the DCB are presented in OS/VS Data Management 
Macro Instructions, GC26-3793. 

Bit of flag 1 in the DCB-address parameter is set to a value of except when: 

• Volume trailer or header labels are being processed at volume switch time. 

• The trailer labels of a MOD data set are being processed (when the data set is 
opened). 

If an uncorrectable input/output error occurs while reading or writing a user 
label, the appropriate label processing routine is entered with bit of flag 2 in 
the status information address parameter set on. The three low order bytes of 
this parameter contain the address of standard status information as supplied for 
SYNAD routines. (The SYNAD routine is not entered.) 

Nonlabel Processing Routine Parameters 

Table 26-1 shows the program from which exits can be taken to nonlabel 
processing routines, the names of the exits, and the parameters available for each 
exit routine. 



Table 26-1. 

Program 
IEBGENER 



Parameter Lists for Nonlabel Processing Exit Routines 



IEBCOMPR 

IEBPTPCH 
IEBTCRIN 



Exit 
KEY 

DATA 
IOERROR 



ERROR 
PRECOMP 

INREC 
OUTREC 

ERROR 
OUTREC 



Parameters 

Address at which key is to be placed (record follows key); 

address of dcb. 

Address of SYSUTl record; address of DCB., 

Address of decb; cause of the error and address of DCB. 

(Address in lower order three bytes and cause of error in high 

order byte.) 

Address of DCB for SYSUTl; address of DCB for SYSUT2. 1 
Address of SYSUTl record; length of SYSUTl record, address of 
SYSUT2 record; length of SYSUT2 record. 

Address of input record; length of the input record. 
Address of output record; length of output record. 

Address of the error record; address of a full word which 
contains the record length. 

Address of the normal record; address of a full word which 
contains the record length. 



1 The iobad pointer in the DCB points to a location that contains the address of the 
corresponding data event control block (DECB) for these records. The format of the DECB is 
illustrated as part of the bsam read macro instruction in OS/VS Data Management Macro 
Instructions, GC26-3793. 



Returning from an Exit Routine 



An exit routine returns control to the utility program by means of the macro 
return instruction in the exit routine. 

The format of the RETURN macro instruction is: 

[labei] RETURN [(rl,r2)] 

,RC= {n} 

{15} 
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where: 

(rl,r2) 

specifies the range of registers to be reloaded by the utility program from the 
register save area. If this parameter is omitted, the registers are considered 
properly restored by the exit routine. 

RC= 

specifies a return code in register 15. If RC is omitted, register 15 is loaded as 
specified by (rl,r2). These values can be coded: 

n 

specifies a return code to be placed in the 12 low order bits of register 15. 

15 

specifies that general register 15 already contains a valid return code. 

The user's label processing routine must return a code in register 15 as shown in 
Table 26-2 unless: 

• The buffer address was set to zero before entry to the label processing 
routine. In this case, the system resumes normal processing regardless of the 
return code. 

• The user's label processing routine was entered after an uncorrectable output 
error occurred. In this case the system attempts to resume normal processing. 

Table 26-2 shows the return codes that can be issued to utility programs by user 
exit routines. Slightly different return codes are used for the UPDATE=INPLACE 
option of the IEBUPDTE program. See the discussion of UPDATE=INPLACE in the 
chapter "IEBUPDTE Program." 

Note: For a list of return codes issued by IEBTCRIN at job termination, see the; 
"IEBTCRIN Program" chapter of this publication. 
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Table 26-2. Return Codes Issued by User Exit Routines 



Type of Exit 

Input Header or 
Trailer Label 



Return 
Code 



4 



Output Header or 
Trailer Label 



Totaling Exits 



16 



4 
8 

16 



4 
8 

16 

All other exits 0- 1 1 

(except IEBTCRIN's (Set to 

ERROR and OUTREC, next 

and IEBPTPCH's multiple 

exit OUTREC) of four) 

12 or 16 
ERROR 



16 



OUTREC (IEBTCRIN) 

4 



OUTREC (IEBPTPCH) 



16 

4 

12 or 16 

Any 

other 

number 



Act/on 

The system resumes normal processing. If there are 
more labels in the label group, they are ignored. 

The next user label is read into the label buffer area and 
control is returned to the user's routine. If there are no 
more labels, normal processing is resumed. 

The utility program is terminated on request of the user 
routine. 

The system resumes normal processing. 

No label is written from the label buffer area. 

The user label is written from the label buffer area. The 
system then resumes normal processing. 

The user label is written from the label buffer area. If 
fewer than eight labels have been created, the user's 
routine again receives control so that it can create another 
user label. If eight labels have been created, the system 
resumes normal processing. 

The utility program is terminated on request of the user 
routine. 

Processing continues, but no further exits are taken. 

Normal operation continues. 

Processing ceases, except for EOD processing on output 
data set (user label processing). 

Utility program is terminated. 

Return code is compared to highest previous return code; 
the higher is saved and the other discarded. At the normal 
end of job, the highest return code is passed to the 
calling processor. 

Utility program is terminated and this return code is 
passed to the calling processor. 

Record is not placed in the error data set. Processing 
continues with the next record. 

Record is placed in the error data set (SYSUT3). 

Record is not placed in error data set but is processed as a 
valid record (sent to OUTREC and SYSUT2 if specified). 
IEBTCRIN removes the EDW from an edited MTDI record 
before processing continues. 

Utility program is terminated. 

Record is not placed in normal output data set. 

Record is placed in normal output data set (SYSUT2). 

Utility program is terminated. 

Record is not placed in normal output data set. 

Utility program is terminated. 

Record is placed in normal output 
data set (SYSUT2). 



Further information on the use of the RETURN macro instruction is contained in 
OS/VS Supervisor Services and Macros, GC27-6979. 
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Appendix B: Invoking Utility Programs from a Problem Program 



Utility programs can be invoked by a problem program through the use of the 
ATTACH or LINK macro instruction. In addition, IEBTCRIN can be invoked 
through the use of the LOAD or call macro instruction. 

The problem program must supply the following to the utility program: 

• The information usually specified in the PARM parameter of the EXEC 
statement. 

• The ddnames of the data sets to be used during processing by the utility 
program. 

Note: When IEHMOVE, IEHPROGM, iehlist, or iehucat is dynamically invoked 
in a job step containing a program other than one of these four, the DD 
statements defining mountable devices for the IEHMOVE, IEHPROGM, IEHLIST, or 
IEHUCAT program must be included in the job stream prior to DD statements 
defining data sets required by the other program. 



LINK or ATTACH Macro Instruction 



The LINK or ATTACH macro instruction can be used to invoke a utility program 
from a problem program. 

The format of the LINK or ATTACH macro instruction is: 

[name] {LINK} EP=progname 
{ATTACH} 

^PARAM^optionaddr^ddnameaddr^hdingaddr]) 

,VL=1 

where: 

EP=progname 

specifies the symbolic name of the utility program. 

PARAM= 

specifies, as a sublist, address parameters to be passed from the problem 
program to the utility program. These values can be coded: 

optionaddr 

specifies the address of an option list, which is usually specified in the 
PARM parameter of the EXEC statement. This address must be written for 
all utility programs. 

ddnameaddr 

specifies the address of a list of alternate ddnames for the data sets used 
during utility program processing. If standard ddnames are used and this is 
not the last parameter in the list, it should point to a halfword of zeros. If it 
is the last parameter, it may be omitted. 

hdingaddr 

specifies the address of a six-byte list, HDNGLIST, which contains an 
EBCDIC page count for the output device. If hdingaddr is omitted, the page 
number defaults to 1 . 

VL=1 

specifies that the sign bit of the last fullword of the address parameter list is 
to be set to 1. 
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Figure 27-1 shows these lists as they exist in the user's DC area.. Note that the 
symbolic starting addresses for OPTLIST and DDNMELST fall on halfword 
boundaries. Note also the alternative ddnames instream, INPUTSET, and 

WHICHPTR. 



Starting address of 
the optionaddr 
parameter list 
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Figure 27-1. Typical Parameter Lists 

The param parameter of the LINK macro instruction in the calling program 
provides the utility program with the symbolic addresses of the parameter lists 
shown in Figure 27-1, as follows: 

• The option list, OPTLIST, which includes the number of bytes in the list 
(hexadecimal 08) and the NOVERIFY option. 

• The alternate ddname list, DDNMELST, which includes the number of bytes in 
the list (hexadecimal 48) and alternative names for the SYSIN, SYSUTl, and 
SYSUT2 data sets. 

• The heading list, HDNGLIST, which includes the number of bytes in the list 
(hexadecimal 04) and indicates the starting page number (shown as 10) for 
printing operations controlled through the SYSPRINT data set. 

The option list, OPTLIST, must begin on a halfword boundary that is not also a 
fullword boundary. The two high order bytes contain a count of the number of 
bytes in the remainder of the list. (For all programs except IEHMOVE, IEHLIST, 
IEHPROGM, IEHINITT, IEHLIST, and IEBISAM, the count must be zero.) OPTLIST 
is free form with fields separated by commas. No blanks or zeros should appear 
in the list. 

The ddname list, DDNMELST, must begin on a halfword boundary that is not also 
a fullword boundary. The two high order bytes contain a count of the number of 
bytes in the remainder of the list. Each name of fewer than eight bytes must be 
left aligned and padded with blanks. If an alternate ddname is omitted from the 
list, the standard name is assumed. If the name is omitted within the list, the 
eight-byte entry must contain binary zeros. Names can be omitted from the end 
by merely shortening the list. Table 27-1 shows the sequence of the eight-byte 
entries in the ddname list pointed to by ddnameaddr. 
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LOAD Macro Instruction 



CALL Macro Instruction 



Table 


27-1. Sequence o 


Entry 


Standard Name 


1 


00000000 


2 


00000000 


3 


00000000 


4 


00000000 


5 


SYSIN 


6 


SYSPRINT 


7 


00000000 


8 


SYSUT1 


9 


SYSUT2 


10 


SYSUT3 


11 


SYSUT4 



The first two bytes of HDNGLIST contain the length in bytes of the heading list. 
The remaining four bytes contain .a page number that the utility program is to 
place on the first page of printed output. 



IEBTCRIN can be invoked through use of the LOAD macro instruction. 

The LOAD macro instruction causes the control program to bring the load module 
containing the specified entry point into main storage unless a copy is already 
there. Control is not passed to the load module. 

The format of the load macro instruction is: 

[name] LOAD {EP=IEBTCRIN} 

{EPLOC= address of name} 

where: 

EP=IEBTCRIN 

is the entry point name of the program to be brought into main storage. 

EPLOC= address of name 

is the main storage address of the entry point name described above. 



The CALL macro instruction can be used to pass control to IEBTCRIN after 
IEBTCRIN has been loaded into main storage. 

Control can be passed to IEBTCRIN via a CALL macro instruction or via a branch 
and link instruction. If the branch and link instruction is used, register 1 must be 
loaded with the address of a parameter list of full words as described under 
"LINK or ATTACH Macro Instruction." The last parameter list address must 
contain X'80' in byte 1 to indicate the last parameter in the list. 

The format of the CALL macro instruction is: 

[name] CALL IEBTCRIN(,opr/bnaddr[,ddnameaddr][,hd/ngaddr]),VL 

where: 

IEBTCRIN 

is the name of the entry point to be given control; the name is used in the 
macro instruction as the operand of a V-type address constant. 

optionaddr 

specifies the address of an option list, OPTLIST, usually specified in the PARM 
parameter of the EXEC statement. This address must be written for all utility 
programs. 
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ddnameaddr 

specifies the address of a list of alternate ddnames, DDNMELST, for the data 
sets used during utility program processing. If standard ddnames are used and 
this is not the last parameter in the list it should point to a halfword of zeros. 
If it is the last parameter, it may be omitted. 

hdingaddr 

specifies the address of a six-byte list containing an EBCDIC page count for 
the output device. 

VL 

specifies that the high order bit of the last address parameter in the macro 
expansion is to be set to 1. 

The option list, OPTLIST, must begin on a halfword boundary that is not also a 
fullword boundary. The two high order bytes contain a count of the number of 
bytes in the remainder of the list. (For all programs except IEHMOVE, 
IEHPROGM, IEHINITT, and IEBISAM, the count must be zero.) The option list is 
free form with fields separated by commas. No blanks or zeros should appear in 
the list. 

The ddname list, DDNMELST, must begin on a halfword boundary that is not also 
a fullword boundary. The two high order bytes contain a count of the number of 
bytes in the remainder of the list. Each name of fewer than eight bytes must be 
left aligned and padded with blanks. If an alternate ddname is omitted from the 
list, the standard name is assumed. If the name is omitted within the list, the 
eight-byte entry must contain binary zeros. Names can be omitted from the end 
by merely shortening the list. The sequence of the eight-byte entries in the 
ddname list pointed to by ddnameaddr is shown earlier in Table 27-1. 

The first two bytes of the heading list, HDNGLIST, contain the length in bytes of 
the heading list. The remaining four bytes contain a page number that the utility 
program is to place on the first page of printed output. 
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Appendix C: DD Statements for Defining Mountable Devices 



When defining mountable devices to be used by system utility programs 
IEHPROGM, IEHMOVE, IEHLIST, or iehdasdr, the user must consider the 
implications of the DD statements he uses to define those devices. 

DD statement parameters must ensure that no one else has access to either the 
volume or the data set. In any case, caution should be used when altering 
volumes that are permanently resident or reserved (for example, volumes 
containing system data sets, non-demountable volumes, and volumes reserved 
through the PRESRES option). 

Under normal conditions, a mountable device should not be shared with another 
job step; that is, if a utility program is used to update a volume on a mountable 
device, the volume being updated must remain mounted until the operation is 
completed. 

Following are ways to ensure that mountable devices are not shared: 

• Specify DEFER in a DD statement defining a mountable device. 

• Specify unit affinity on a second DD statement defining a mountable device. 

• Specify a volume count in the VOLUME parameter of a DD statement that is 
greater than the number of mountable devices to be allocated. 

• Specify PRIVATE in a DD statement defining a mountable device. 
For a detailed discussion, see OS/VS JCL Reference, GC28-0618. 



DD Statement Examples 



DD Example 1 



In the following examples of DD statements, an IBM 2314 Disk Storage Drive is 
indicated as the mountable device. Alternative parameters are stacked. 



This DD statement makes a specific request for a private, non-sharable volume or 
volumes to be mounted on a single 2314 device. 

The example follows: 

//DD1 DD UNIT=( 2314, , DEFER ),DISP=( , KEEP), 
// VOLUME=( PRIVATE, SER=( 123456) ) 

A utility program causes a mount message to be issued for a specific volume 
when the volume is required for processing by the program. The user should 
supply the operator with the clearly marked volume or volumes to be mounted 
during the job step. 

This DD statement ensures that the volume integrity of a mountable volume is 
maintained. If only one volume is to be processed, it is mounted at the start of 
the job step and demounted at the end of the step. If additional volumes are 
processed, they are mounted and demounted when needed by the utility program. 
The last volume to be processed is demounted at the end of the job step. 
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DD Example 2 



DD Example 3 



DD Example 4 



DD Example 5 



This DD statement makes a request for a private, non-sharable volume. 
The example follows: 

//DD2 DD UNI T=( 2314, , DEFER ) , VOLUME=PRIVATE,DISP=( NEW, KEEP) 

The results of this statement are identical to those shown in DD Example 1. 

If a specific unit is requested and the volume serial number is not given in the 
DD statement, the user must be certain that either: (1) the desired volume is 
already mounted on that unit, or (2) a volume is not mounted, causing the 
system to issue a mount message. 

Note: This statement can be used only if the user is certain that a removable 
volume, rather than a fixed volume, will be allocated by the scheduler. If there is 
any chance that a fixed volume will be allocated, this statement must not be 
used. '' 



This DD statement makes a specific request for a private, sharable volume to be 
mounted on a 2314 device. 

The example follows: 

//DD1 DD UN IT=2 3 14, VOLUMES PRIVATE, SER=( 121212 ) ),DISP=OLD 

This DD statement does not ensure that volume integrity is maintained. It should 
be used with extreme caution in a multiprogramming environment because there 
is the possibility that a job step running concurrently might make a specific 
request for the volume, use the volume, and demount it. 



This DD statement makes a specific request for a public, non-sharable volume to 
be mounted on a 2314 device. 

The example follows: 

//DD3 DD UNIT=( 2314, , DEFER ) , VOLUME=SER=7890 12, DISP=OLD 

If the volume is already mounted, it is used. The volume remains mounted at the 
end of the job step, and is not demounted until another job step requires the 
device on which the volume is mounted. 

This DD statement ensures that volume integrity is maintained between jobs; two 
or more such statements in a single job can allocate the same device. 



This DD statement makes a specific request for a public, sharable volume to be 
mounted on a 2314 device. 

The example follows: 

//DD1 DD UNIT=2314,VOLUME=SER=654321 ,DISP=OLD 

If the volume is already mounted, it is used. The volume remains mounted at the 
end of the job step, and is not demounted until another job step requires the 
device on which the volume is mounted. (This DD statement can also be used to 
define permanently resident devices.) 

This DD statement does not ensure that the volume integrity of a mountable 
volume is maintained. It should be used with extreme caution in a 
multiprogramming environment because there is the possibility that a job step 
running concurrently might use the device. 
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Appendix D: Processing User Labels 



User labels can be processed by IEBGENER, IEBCOMPR, IEBPTPCH, IEHMOVE, 
IEBCTRIN, and IEBUPDTE. In some cases, user-label processing is automatically 
performed; in other cases, you must indicate the processing to be performed. In 
general, user label support allows the utility program user to: 

• Process user labels as data set descriptors. 

• Process user labels as data. 

• Total the processed records prior to each WRITE command (IEBGENER and 
IEBUPDTE only). 

For either of the first two options, the user must specify standard labels (SUL) on 
the DD statement that defines each data set for which user-label processing is 
desired. For totaling routines, OPTCD=T must be specified on the DD statement. 

The user cannot update labels by means of the IEBUPDTE program. This function 
must be performed by a user's label processing routines. IEBUPDTE will, however, 
allow you to create labels on the output data set from data supplied in the input 
stream. See the discussion of the label statement in the chapter "IEBUPDTE: 
Program." 

IEHMOVE does not allow exits to user routines and does not recognize options 
concerning the processing of user labels as data. IEHMOVE always moves or 
copies user labels directly to a new data set. See the chapters for the "IEHMOVE 
Program." 

Volume switch labels of a multivolume data set cannot be processed by 
IEHMOVE, IEBGENER, or IEBUPDTE. Volume switch labels are therefore lost 
when these utilities create output data sets. To ensure that volume switch labels 
are retained, process multivolume data sets one volume at a time. 

Processing User Labels as Data Set Descriptors 

When user labels are to be processed as data set descriptors, one of the user's 
label processing routines receives control for each user label of the specified type. 
The user's routine can include, exclude, or modify the user label. Processing of 
user labels as data set descriptors is indicated on an EXITS statement with 
keyword parameters that name the label processing routine to be used. 

The EXIT keyword parameters indicate that a user routine should receive control 
each time the OPEN, EOV, or CLOSE routine encounters a user label of the type 
specified. 

Figure 29-1 illustrates the action of the system at OPEN, EOV, or CLOSE time. 
When OPEN, EOV, or CLOSE recognizes a user label and when SUL has been 
specified on the DD statement for the data set, control is passed to the utility 
program. Then, if an exit has been specified for this type of label, the utility 
program passes control to the user routine. The user's routine processes the label 
and returns control, along with a return code, to the utility program. The utility 
program then returns control to OPEN, EOV, or CLOSE. 
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OPEN/EOV/CLOSE 



IZZ 



Utility program 



User's label 
processing routine 



Figure 29-1. System Action at open, eov, or close Time 

This cycle is repeated up to eight times, depending upon the number of user 
labels in the group and the return codes supplied by the user's routine. 

Exiting to a User's Totaling Routine 

When an exit is taken to a user's totaling routine, an output record is passed to 
the user's routine just before the record is written. The first halfword of the 
totaling area pointed to by the parameter contains the length of the totaling area, 
and should not be used by the user's routine. If the user has specified user label 
exits, this totaling area (or an image of this area) is pointed to by the parameter 
list passed to the appropriate user label routine. 

Note: An output record is defined as a physical record (block), except when 
IEBGENER is used to process and reformat a data set that contains spanned 
records. 

Processing User Labels as Data 

When user labels are processed as data, the group of user labels, as well as the 
data set, is subject to the normal processing done by the utility program. The 
user can have his labels printed or punched by IEBPTPCH, compared by 
1EBCOMPR, or copied by IEBGENER. 

To specify that user labels are to be processed as data, include a LABELS 
statement in the job step that is to process user labels as data. 

There is no direct relationship between the LABELS statement and the EXITS 
statement. Either or both can appear in the control statement stream for an 
execution of a utility program. If there are user label-processing routines, 
however, their return codes may influence the processing of the labels as data. In 
addition, a user's output label-processing routine can override the action of a 
LABELS statement because it receives control before each output label is written. 
At this time the label created by the utility as a result of the LABEL statement is 
in the label buffer, and the user's routine can modify it. 

The code returned by the user's totaling routine determines system response as 
follows: 

• 0, which specifies that processing is to continue, but no further exits are to be 
taken. 

• 4, which specifies that normal processing is to continue. 

• 8, which specifies that processing is to terminate, except for EOD processing 
on the output data set (user label processing). 

• 16, which specifies that processing is to be terminated. 
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Index 



Indexes to systems reference library manuals are consolidated 
in OS/VS Master Index, GC28-0602. For additional information 
about any subject listed below, refer to other publications listed 
for the same subject in the Master Index. 

Note: If more than one page number is given, the primary 
discussion is listed first. 
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combinations of NEW, MEMBER, and NAME keywords 13-9 

comments on utility control statements 1-2 

COMPARE statement 5-3 

comparing 

partitioned directories 5-1 

partitioned data sets 5-1 

records 5-1 

sequential data sets 5-1 

compatible volumes (VS1) 20-2 

compatible volumes (VS2) 21-2 

compress-in-place 6-4,6-5 

compressing a data set 6-4,6-5 

concatenating SYSIN data sets when using IEHDASDR . 15-9 
concurrent operations when using IEHDASDR, 

specifying 15-8 

CONNECT statement 22-16 

connecting two control volumes 22-4,22-16 

considerations for defining DD statements 28-1 

continuing utility control statements 1-2 

control passwords 

adding (VS1) 22-8 

adding (VS2) 23-4 

deleting (VS1) 22-8 

deleting (VS2) 23-4 

listing information from (VS1) 22-9 

listing information from (VS2) 23-5 

maintaining (VS1) 22-6 

maintaining (VS2) 23-2 

replacing (VS1) 22-8 

replacing (VS2) 23-4 

control statements 

comments on 1-2 

continuing 1-2 

format of 1-2 

restrictions 1-2 

control volumes 

connecting 22-4,22-16 

copying 20-8 

disconnecting 22-4,22-17 

moving 20-8 

controlling 

IBCDASDI 2-2 

IBCDMPRS 3-1 

ICAPRTBL 4-1 

IEBCOMPR 5-2 

IEBCOPY 6-6 

IEBDG 7-4 

IEBEDIT 8-2 

IEBGENER 9-4 

IEBISAM 10-5 

IEBPTPCH 11-3 

IEBTCRIN 12-7 

IEBUPDTE 13-2 

IEHATLAS 14-2 

IEHDASDR 15-7 

IEHINITT 16-2 

IEHIOSUP 17-1 

IEHLIST (VS1) 18-5 



IEHLIST (VS2) 19-5 

IEHMOVE (VS1) 20-10 

IEHMOVE (VS2) 21-9 

IEHPROGM (VS1) 22-9 

IEHPROGM (VS2) 23-5 

IEHUCAT 24-2 

IFHSTATR 25-2 

conventions, notational viii 

converting a data set 

from sequential to partitioned organization . 9-1,13-1,13-6 
converting a member of a partitioned data set to a 

sequential data set 13-1,13-6 

converting data 

from alphameric to hexadecimal 11-11 

from H-set BCD to EBCDIC 9-11,9-3 

from packed to unpacked decimal . . . 11-11,9-10,9-11,9-3 

from unpacked to packed decimal 9-10,9-11,9-3 

COPY statement 6-9 

COPY CATALOG statement 20-22 

COPY DSGROUP statement 20-17 

COPY DSNAME statement (VS1) 20-14 

COPY DSNAME statement (VS2) 21-14 

copy operation 6-9 

COPY PDS statement (VS1) 20-19 

COPY PDS statement (VS2) 21-16 

COPY VOLUME statement (VS1) 20-23 

COPY VOLUME statement (VS2) 21-18 

copying 

aBDAMdataset (VS1) 20-5 

a BDAM data set (VS2) 21-5 

a catalog 20-8,20-22 

a data set (VS1) 6-1,6-2,20-2,20-4,20-15 

a data set (VS2) 6-1,6-2,21-4,21-6,21-14 

a direct data set with variable spanned records (VS1) . 20-9 
a direct data set with variable spanned records (VS2) . 21-8 

a dumped data set 15-4 

a group of data sets 20-7,20-17 

a member with an alias 6-1 

a partitioned data set (VS1) 6-2,20-4,20-5,20-19 

a partitioned data set (VS2) . . . 6-2,21-4,21-5,21-6,21-16 

a volume of data sets (VS1) 20-8,20-23,15-3 

a volume of data sets (VS2) 21-7,21-8,21-18,15-3 

an indexed sequential data set (VS1) 10-1,20-5 

an indexed sequential data set (VS2) 10-1,21-6 

an unloaded data set (VS1) 6-1,6-2,20-1 

an unloaded data set (VS2) 6-1,6-2,21-1 

members of a partitioned 

data set (VS1) 6-1,6-2,20-6,20-24,20-25,20-26 

members of a partitioned 

data set (VS2) 6-1,6-2,21-3,21-6,21-19,21-20 

records 9-4 

sequential data sets (VS1) 6-2,20-5,20-4 

sequential data sets (VS2) 6-2,21-4,21-6 

user labels 9-5 

CREATE statement 7-11 

creating 

a backup copy 

using IEBCOPY 6-2 

using IEBGENER 9-1 

using IEHDASDR 15-3,15-1 

a library 13-1 

a symbolic library 13-1 

a partitioned data set from sequential input 9-1 

a sequential copy of an indexed sequential data set . . 10-1 

a sequential output data set 12-1,8-1 

a sequential output job stream 8-1 

an edited data set 9-2 
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user header labels 13-12,13-13 

user trailer labels 13-13 

D 

DADEF statement 2-3 

DASDI, Quick 2-1,15-12,15-28 

DASDI program (see IBCDASDI) 

data 

dumped 15-1,15-3,15-4,15-15,3-1 

movable (VS1) 20-3 

movable (VS2) 21-3 

reconstructed (VS1) 10-1,20-1 

reconstructed (VS2) 10-1,21-1 

reorganized (VS1) 20-1 

reorganized (VS2) 21-1 

unloaded (VS1) 10-1,20-1 

unloaded (VS2) 10-1,21-1 

unmovable (VS1) 20-1,20-3 

unmovable (VS2) . . . 21-1,21-3 

data set control block (DSCB), alter or set protection 

status in (VS1) . . . 22-6,22-7,22-8,22-9,22-18,22-19,22-20 

data set control block (DSCB), alter or set protection 

status in (VS2) . . .23-2,23-3,23-4,23-10,23-11,23-12,23-13 

data set passwords 

adding (VS1) 22-8 

adding (VS2) 23-4 

deleting (VS1) 22-8 

deleting (VS2) 23-4 

listing (VS1) 22-9 

listing (VS2) 23-5 

maintaining (VS1) 22-6 

maintaining (VS2) . . . . ' 23-1 

replacing (VS1) 22-8 

replacing (VS2) 23-4 

data set utility programs 

IEBCOMPR 5-1 

IEBCOPY 6-1 

IEBDG 7-1 

IEBEDIT 8-1 

IEBGENER 9-1 

IEBISAM 10-1 

IEBPTPCH 11-1 

IEBTCRIN 12-1 

IEBUPDTE 13-1 

introduction 1-3 

data sets 

adding 13-5 

cataloging (VS1) 22-2 

cataloging (VS2) 23-1 

changing 13-5 

compressing 6-5 

converting 9-1,13-1 

copying (VS1) 10-1,6-1,20-1 

copying (VS2) 10-1,6-1,21-1 

dumping 3-1 

editing 9-2,9-3 

expanding 9-2 

loading 10-1 

merging 6-1 

modifying 13-5 

moving (VS1) 20-1 

moving (VS2) 21-1 

protecting (VS1) 22-6 

protecting (VS2) 23-2 

reconstructing (VS1) 20-1 

reconstructing (VS2) 21-1 

re-creating (VS1) 6-5,20-1 



re-creating (VS2) 6-5,21-1 

renaming (VS1) 22-1 

renaming (VS2) 23-1 

replacing 13-5 

reproducing 13-5 

scratching (VS1) . . . 22-1,22-12 

scratching (VS2) 23-1 ,23-7 

uncataloging (VS1) 22-2,22-14 

uncataloging (VS2) 23-2,23-10 

unloading (VS1) 20-1,10-1 

unloading (VS2) 21-1,10-1 

data sets, moving or copying a group of cataloged .... 20-7 
data sets, partitioned (see partitioned data sets) 

Data statement 13-11 

DD names, alternate 27-1 

DD statements, attributes of 28-1 

DD statements, operational results of 28-1,28-1 

deblocking with IEBCOPY 6-7 

defective track 

assign alternate tracks for 14-1,15-1,2-1 

flagging 15-1 

indicated by data check 14-1 

indicated by IEHATLAS 14-1 

indicated by missing address marker 14-1 

recovering data from 14-1 

testing for 15-1,2-1 

deferred mounting, specifying 28-1 

defining data sets 

with the IEBCOMPR program 5-3 

with the IEBCOPY program 6-7 

with the IEBDG program 7-4 

with the IEBEDIT program 8-2 

with the IEBGENER program 9-5 

with the IEBISAM program 10-5 

with the IEBPTPCH program 11-3 

with the IEBTCRIN program 12-7 

with the IEBUPDTE program 13-2 

with the IEHATLAS program 14-2 

with the IEHDASDR program 15-7 

with the IEHINITT program 16-3 

with the IEHIOSUP program 17-1 

with the IEHLIST program (VS1) 18-6 

with the IEHLIST program (VS2) 19-5 

with the IEHMOVE program (VS1) 20-10 

with the IEHMOVE program (VS2) 21-10 

with the IEHPROGM program (VS1) 22-10 

with the IEHPROGM program (VS2) 23-6 

with the IEHUCAT program 24-2 

with the IFHSTATR program 25-2 

defining mountable devices 28-1 

DELETE 13-9 

DELETEP statement (VS1) 22-20 

DELETEP statement (VS2) 23-12 

deleting 

a logical record 13-10 

an index 22-3 

an index alias 22-4 

data set passwords (VS1) 22-8,22-20 

data set passwords (VS2) 23-4,23-12 

demounting mountable volumes 28-2 

Detail statement 13-9 

device name 1-2 

DFN statement 4-1 

direct access volumes 

assigning alternate tracks to 

using IBCDASDI 2-1 

using IEHATLAS 14-1 

using IEHDASDR 15-3 
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dumping 3-1,3-2,15-1,15-15 

initializing 

using IBCDASDI 2-1 

using IEHDASDR 15-1,15-2 

restoring 3-1 

direct data sets, moving or copying (VS1) 20-4,20-8 

direct data sets, moving or copying (VS2) 21-4,21-7 

with variable spanned records (VS1) 20-9 

with variable spanned records (VS2) 21-8 

directory entry, format of 18-2 

directory, partitioned data set listing 18-1 

disconnecting volumes 22-4 

DLTA statement 22-16 

DLTX statement 22-15 

DSCB 

set or alter protection status in (VS1) . . 22-6,22-18,22-20 
set or alter protection status in (VS2) . . 23-2,23-10,23-12 

DSD statement 7-6 

dummy header label 16-1 

DUMP statement 

for IBCDMPRS program 3-2 

for IEHDASDR program 15-15 

DUMP/RESTORE program (see IBCDMPRS) 

dumping a direct access volume 3-1,3-2,15-1,15-15 

dumping multiple volumes to a single restore tape ... 15-18 

dumping unlike devices 15-4 

DUP (see TCRGEN statement) 
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EDIT statement 8-2 

edited format 

ofaVTOC(VSl) 18-3 

of a VTOC (VS2) 19-2 

of a PDS directory entry (VS1) 18-1 

of a PDS directory entry (VS2) 19-1 

editing 

data 12-1,12-5 

sequential data set 9-2,9-3 

partitioned data set 9-2,9-3 

editing facilities 

with the IEBGENER program 9-2 

with the IEBPTPCH program 11-2 

with the IEBTCRIN program 12-5,12-6 

ellipsis, use of ix 

END statement 

for IBCDASDI 2-6 

for IBCDMPRS 3-4 

for ICAPRTBL 4-3 

for IEBDG 7-16 

end-of-cartridge 12-6 

end-of-file (EOF) record, assigning alternate track .... 14-4 

end-of-record 12-3 

ENDUP statement 13-14 

ensuring volume integrity 28-1 

entering job control statements into a 
procedure library 13-15 

EOR 12-2,12-3 

EOV module, changing or replacing 17-1 

ESV record 

format 25-1 

processing 25-1 

examples 

IBCDASDI 2-5,2-6 

IBCDMPRS 3-5 

ICAPRTBL 4-3 

IEBCOMPR 5-5 

IEBCOPY 6-13,6-14 



IEBDG 7-16 

IEBEDIT 8-4 

IEBGENER 9-11 

IEBISAM 10-6 

IEBPTPCH 11-13 

IEBTCRIN . . . 12-16 

IEBUPDTE 13-14 

IEHATLAS 14-3 

IEHDASDR 15-20,15-21 

IEHINITT 16-5 

IEHIOSUP 17-2 

IEHLIST (VS1) 18-9 

IEHLIST (VS2) 19-8 

IEHMOVE(VSl) 20-26,20-27 

IEHMOVE (VS2) 21-20,21-21 

IEHPROGM (VS1) 22-21,22-22 

IEHPROGM (VS2) 23-13,23-14 

IEHUCAT 24-3 

IFHSTATR 25-3 

exceptions to control statement requirements 1-2 

EXCLUDE statement 

for IEBCOPY 6-13 

for IEHMOVE (VS1) 20-25 

for IEHMOVE (VS2) 21-19 

excluding data from move and copy operations 6-4 

exclusive copy operation 6-4,6-13 

executing 

a data set utility program 1-3,1-4 

a system utility program 1-3 

an independent utility program 1-4,1-5 

EXIT (on IEBISAM PARM) 10-5 

exit routine linkage 26-1 

exit routines 

location of 26-1 

parameter lists for 26-2 

return codes issued by 26-4,29-2 

EXITS statement 

for IEBCOMPR 5-4 

for IEBGENER 9-7 

for IEBPTPCH 11-9 

for IEBTCRIN 12-14 

expanding a partitioned data set 9-2,9-3 

expiration date, specifying (VS I) 20-11 

expiration date, specif yiny (VS2) 21-11 
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FCB 

loading of 4-2 

statement 4-2 

FD statement 7-6 

FEOV module, changing or replacing 17-1 

field processing and editing information, specifying 9-10,11-11 

flagged defective tracks, checking for 2-1,15-1 

FORMAT statement 15-12 

format of utility control statements 1-2 

forms control buffer, loading the 4-2 

Function statement 13-4 

functions, guide to utility program xxv 
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general uses 

for data set utility programs 1-3,1-4 

for independent utility programs 1-4 

for system utility programs 1-3 

GENERATE statement 9-6 

generating test data 7-1 
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generic name 1-2 

GETALT statement 

for IBCDASDI program 2-5 

for IEHDASDR program 15-15 

H 

header record, initializing 16-1 

H-set BCD to EBCDIC conversion 9-11 

I 

IBCDASDI program 2-1 

control of 2-2 

utility control statements 2-2 

examples 2-5,2-6 

executing 1-4 

input and output 2-2 

used to 

assign an alternate track 2-1 

initialize a direct access volume 2-1 

utility control statements 2-2 

DADEF 2-3 

END 2-6 

GETALT 2-5 

IPLTXT 2-5 

JOB 2-2 

LASTCARD 2-6 

MSG 2-2 

VLD 2-4 

VTOCD 2-4 

IBCDMPRS program 3-1 

control of 3-1 

utility control statements 3-1 

examples 3-5 

executing 1-4 

input and output 3-1 

used to 

dump data 3-1,3-2 

restore data 3-1,3-4 

utility control statements 3-1 

DUMP 3-2 

END 3-4 

JOB 3-1 

MSG 3-1 

RESTORE 3-4 

VDRL 3-3 

ICAPRTBL program 4-1 

codes, wait state 1-5 

control of 4-1 

utility control statements 4-1 

example 4-3 

executing 1-5 

input and output 4-1 

used to 

load forms control buffer 4-2 

load Universal Character Set buffer 4-2 

utility control statements 4-1 

DFN 4-1 

END 4-3 

FCB 4-2 

JOB 4-1 

UCS 4-2 

wait state codes 1-5 



IEBCOMPR program 5-1 

codes, return 5-2 

control of 5-2 

job control statements 5-3 

restrictions 5-3 

utility control statements 5-3 

examples 5-5 

input and output 5-2 

return codes 5-2 

used to 

compare partitioned data sets 5-1 

compare sequential data sets 5-1 

verify backup copies 5-1 

utility control statements 5-3 

COMPARE 5-3 

EXITS 5-4 

LABELS 5-4 

IEBCOPY program 6-1 

codes, return 6-6 

control of 6-6 

job control statements 6-6,6-7 

restrictions 6-8 

space allocation 6-8 

utility control statements 6-9 

examples 6-13,6-14 

input and output 6-5 

return codes 6-6 

used to 

compress a data set 6-4 

copy data sets 6-2 

create a backup copy 6-2 

exclude members from a copy operation 6-4 

load data sets 6-2 

merge data sets 6-5 

re-create a data set 6-5 

rename selected members 6-4 

replace identically named members 6-3 

replace selected members 6-4 

select members to be copied 6-2 

select members to be loaded 6-2 

select members to be unloaded 6-2 

utility control statements 6-9 

COPY 6-9 

EXCLUDE 6-13 

SELECT 6-12 

IEBDG program 7-1 

codes, return 7-3 

control of 7-4 

job control statements 7-4 

PARM information 7-5 

restrictions 7-5 

utility control statements 7-6 

examples 7-16 

fields modified by 7-2 

IBM-supplied patterns for 7-1 

input and output 7-3 

modifying selected fields with 7-2 

patterns for - (supplied by IBM) 7-1 

pictures for - (user-specified) 7-2 

return codes 7-3 

selected fields modified by 7-1 

used to 

generate test data 7-1 

modify selected fields 7-2 

user-specified pictures for 7-2 
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utility control statements 7-6 

CREATE 7-11 

DSD 7-6 

END 7-16 

FD 7-6 

REPEAT 7-15 

IEBEDIT program 8-1 

codes, return 8-1 

control of 8-2 

job control statements 8-2 

restrictions 8-2 

utility control statement 8-2 

examples 8-3 

input and output 8-1 

return codes 8-1 

used to 

copy an entire job 8-1 

copy selected job steps 8-1 

utility control statement 8-2 

EDIT 8-2 

IEBGENER program 9-1 

codes, return 9-4 

control of 9-4 

job control statements 9-4 

restrictions 9-5 

utility control statements 9-6 

examples 9-11 

input and output 9-4 

return codes 9-4 

used to 

change logical record length 9-4 

copy user labels on sequential output 9-8 

create a backup copy 9-1 

expand a partitioned data set 9-2 

produce a partitioned data set from sequential input 9-1 

produce an edited data set 9-2 

reblock . 9-4 

utility control statements 9-6 

EXITS 9-7 

GENERATE 9-6 

LABELS 9-8 

MEMBER 9-9 

RECORD 9-9 

IEBISAM program 10-1 

codes, return 10-4 

control of 10-5 

job control statements 10-5 

PARM information 10-5 

examples 10-6 

input and output 10-4 

return codes 10-4 

used to 

copy an indexed sequential data set 10-1 

create a sequential copy of an indexed sequential 

data set 10-1 

create an indexed sequential data set from an 

unloaded data set 10-3 

print an indexed sequential data set 10-3 

IEBPTPCH program 11-1 

codes, return 11-2 

control of 11-3 

job control statements 11-3 

restrictions 11-3 

utility control statements 11-4 

examples 11-13 

input and output 11-2 

return codes 11-2 



used to print or punch 

a partitioned directory 11-2 

an edited data set 11-2 

data sets 11-1 

selected members 11-1 

selected records 11-2 

utility control statements 11-4 

EXITS 11-9 

LABELS 11-12 

MEMBER 11-10 

PRINT 11-4 

PUNCH 11-6 

RECORD 11-10 

TITLE 11-9 

IEBTCRIN program 12-1 

cartridge, end-of- 12-6 

codes 

MTDI, from TCR 12-12 

MTST, after translation 12-14 

MTST, from TCR 12-13 

return 12-16 

special purpose 12-12 

control of 12-7 

job control statements 12-7 

restrictions 12-8 

utility control statements 12-8 

editing 

criteria, MTDI 12-5 

restrictions, MTDI 12-5 

end-of-cartridge 12-6 

error description word (EDW) 12-1 

end-of -record byte 12-3 

level status byte 12-1 

start-of -record byte 12-2 

type status byte 12-2 

error records 12-1 

samples of 12-3 

examples 12-16 

input and output 12-6 

MTDI codes from TCR 12-12 

MTDI editing criteria 12-5 

MTDI editing restrictions „ 12-5 

MTST codes after translation 12-14 

MTST codes from TCR 12-13 

record, end of 12-3 

record, start of 12-3 

records, error 12-1 

samples of 12-3 

return codes 12-16 

special purpose codes 12-12 

status, level 12-1 

status,type 12-2 

used to 

edit data 12-5,12-1 

produce sequential output data 12-1 

read input 12-1 

utility control statements 12-8 

EXITS 12-14 

TCRGEN 12-8 

IEBUPDTE program 13-1 

codes, return 13-2 

control of 13-2 

job control statements 13-2 

PARM information 13-4 

restrictions 13-3 

utility control statements 13-4 

examples 13-14 

input and output 13-1 
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return codes 13-2 

used to 

change data set organization 13-1 

create and update symbolic libraries 13-1 

incorporate source language modifications . . . .13-1 

modify data sets 13-1 

utility control statements 13-4 

ALIAS 13-13 

Data 13-11 

Detail 13-9 

ENDUP 13-14 

Function 13-4 

LABEL 13-12 

IEH ATLAS module, changing or replacing 17-1 

IEHATLAS program 14-1 

control of 14-2 

job control statements 14-2 

restrictions 14-2 

utility control statement 14-2 

examples 14-3 

input and output 14-1 

used to 

assign an alternate track 14-1 

indicate a defective track 14-1 

utility control statement 14-2 

TRACK or VTOC 14-2 

IEHDASDR program 15-1 

codes, return 15-6 

control of 15-7 

job control statements 1 5-7 

PARM information 15-9 

restrictions 15-9 

utility control statements 15-10 

examples 15-20,15-21 

input and output 15-6 

return codes 15-6 

used to 

assign alternate tracks 15-3 

change volume serial numbers 15-3 

copy dumped data 15-4 

create a copy 15-3 

dump unlike devices 15-4 

initialize with recording-surface analysis 15-1 

initialize without recording-surface analysis .... 15-2 

restore unlike devices 15-4 

write IPL records and program 1 5-4 

utility control statements 15-10 

ANALYZE 15-10 

DUMP 15-15 

FORMAT 15-12 

GETALT 15-15 

IPLTXT 15-19 

LABEL 15-14 

PUTIPL 15-19 

RESTORE 15-18 

IEHINITT program 16-1 

codes, return 16-2 

control of 16-2 

job control statements 16-2 

PARM information 16-3 

restrictions 16-3 

utility control statement 16-3 

examples 16-5 

input and output 16-2 

return codes 16-2 

used to place volume label sets on magnetic tape . . .16-1 

utility control statement 16-3 

INITT 16-3 



IEHIOSUP program 17-1 

codes, return 17-1 

control of 17-1 

job control statements 17-1 

restrictions 17-1 

examples 17-2 

input and output 17-1 

return codes 17-1 

used to update TTR entries 17-1 

IEHL1ST program for VS1 Release 3 18-1 

codes, return 18-5 

control of 18-5 

job control statements 18-6 

PARM information 18-7 

restrictions 18-6 

utility control statements 18-7 

examples 18-9 

input and output 18-5 

return codes 18-5 

used to list 

catalog entries 18-1 

directories 18-1 

members of (edited) 18-1 

members of (unedited) 18-2 

volume table of contents 18-3 

entries in (edited) 18-3 

entries in (unedited) 18-5 

utility control statements 18-7 

LISTCTLG 18-7 

LISTPDS 18-8 

LISTVTOC 18-8 

IEHLIST program for VS2 Release 2 19-1 

codes, return 19-5 

control of 19-5 

job control statements 19-5 

PARM information 19-7 

restrictions 19-6 

utility control statements 19-7 

examples 19-8 

input and output 19-5 

return codes 19-5 

used to list 

directories 19-1 

members of (edited) 19-1 

members of (unedited) 19-2 

volume table of contents 19-2 

entries in (edited) 19-2 

entries in (unedited) 19-4 

utility control statements 19-7 

LISTPDS 19-7 

LISTVTOC 19-8 

IEHMOVE program for VS1 Release 3 20-1 

codes, return 20-10 

control of 20-10 

job control statements 20-10 

for track overflow 20-13 

PARM information 20-12 

restrictions 20-12 

utility control statements 20-13 

examples 20-26,20-27 

input and output 20-9 

return codes 20-10 

used to move or copy 

a catalog 20-8 

a data set 20-4 

a group of cataloged data sets 20-7 

a volume of data sets 20-8 

direct data sets with variable spanned records . . 20-9 
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used to reblock data sets 20-4 

utility control statements 20-13 

COPY CATALOG 20-22 

COPY DSGROUP 20-17 

COPY DSNAME 20-15 

COPY PDS 20-19 

COPY VOLUME 20-23 

EXCLUDE 20-25 

INCLUDE 20-24 

MOVE CATALOG 20-21 

MOVE DSGROUP 20-16 

MOVE DSNAME 20-14 

MOVE PDS 20-18 

MOVE VOLUME 20-23 

REPLACE 20-26 

SELECT 20-25 

IEHMOVE program for VS2 Release 2 21-1 

codes, return 21-9 

control of 21-9 

job control statements 21-9,21-10 

for track overflow 21-12 

PARM information 21-12 

restrictions 21-11 

utility control statements 21-12 

examples 21-20,21-21 

input and output 21-9 

return codes 21-9 

used to move or copy 

a data set 21-4 

a volume of data sets 21-7 

direct data sets with variable spanned records . . .21-8 

used to reblock data sets . 21-4 

utility control statements 21-12 

COPY DSNAME 21-14 

COPY PDS 21-16 

COPY VOLUME 21-18 

EXCLUDE 21-19 

INCLUDE 21-18 

MOVE DSNAME 21-13 

MOVE PDS 21-15 

MOVE VOLUME . 21-17 

REPLACE 21-20 

SELECT 21-19 

IEHPROGM program for VS1 Release 3 22-1 

codes, return 22-9 

control of 22-9 

job control statements 22-10 

PARM information 22-11 

restrictions 22-11 

utility control statements 22-11 

examples 22-21,22-22 

input and output 22-9 

return codes 22-9 

used to 

add an entry to PASSWORD data set 22-8 

build a generation index 22-5 

build an index * 22-3 

build an index alias 22-4 

catalog a data set 22-2 

connect two volumes 22-4 

delete an entry from PASSWORD data set 22-8 

delete an index 22-3 

delete an index alias 22-4 

list information from PASSWORD 

data set entries 22-9 

maintain a generation index 22-5 

maintain data set passwords 22-6 

release two volumes 22-4 



rename a data set or member . 22-1 

replace an entry in PASSWORD data set 22-8 

scratch a data set or member 22-1 

uncatalog a data set 22-2 

utility control statements 22-11 

ADD 22-18 

BLDA 22-15 

BLDG 22-17 

BLDX 22-15 

CATLG 22-13 

CONNECT 22-16 

DELETEP 22-20 

DLTA 22-16 

DLTX 22-15 

LIST 22-21 

RELEASE 22-17 

RENAME 22-13 

REPLACE 22-19 

SCRATCH 22-12 

UNCATLG 22-14 

IEHPROGM program for VS2 Release 2 23-1 

codes, return 23-5 

control of 23-5 

job control statements 23-6 

PARM information 23-7 

restrictions 23-6 

utility control statements 23-7 

examples 23-13,23-14 

input and output 23-5 

return codes 23-5 

used to 

add as entry to PASSWORD data set 23-4 

catalog a data set 23-1 

delete an entry from PASSWORD data set ... . 23-4 
list information from PASSWORD 

data set entries 23-5 

maintain data set passwords 23-2 

rename a data set or member 23-1 

replace an entry in PASSWORD data set 23-4 

scratch a data set or member 23-1 

uncatalog a data set 23-1 

utility control statements 23-7 

ADD 23-10 

CATLG 23-9 

DELETEP 23-12 

LIST 23-13 

RENAME 23-8 

REPLACE 23-11 

SCRATCH 23-7 

UNCATLG 23-10 

IEHUCAT program 24-1 

control of 24-2 

job control statements 24-2 

examples 24-3 

input and output 24-1 

use of 24-1 

IFHSTATR program 25-1 

control of 25-2 

job control statements 25-2 

example 25-3 

input and output 25-2 

use of 25-1 

INCLUDE statement (VS1) 20-24 

INCLUDE statement (VS2) 21-18 
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independent utility programs 

IBCDASDI 2-1 

1BCDMPRS 3-1 

1CAPRTBL 4-1 

introduction to 1-4 

index 

building 22-3,22-15 

deleting 22-3,22-15 

generation 22-5,22-17 

index alias 

building 22-4,22-15 

deleting 22-4,22-16 

index structure, listing 18-1 

indexed sequential data sets 

copying 10-1 

creating, from unloaded data set 10-3 

loading 10-1,10-6 

printing 10-5,10-6 

unloading 10-1,10-6 

initializing direct access volumes 

with IBCDASDI 2-1 

with IEHDASDR 15-1,15-2 

with surface analysis 2-1,15-1 

without surface analysis 2-1,15-2,15-1 

INITT statement 16-3 

input stream, organizing 8-1 

input to and output from 

IBCDASDI 2-2 

IBCDMPRS 3-1 

ICAPRTBL 4-1 

IEBCOMPR 5-2 

1EBCOPY 6-5 

IEBDG 7-3 

IEBEDIT 8-1 

IEBGENER 9-4 

IEBISAM 10-4 

IEBPTPCH 11-2 

IEBTCRIN 12-6 

IEBUPDTE 13-1 

IEHATLAS 14-1 

IEHDASDR 15-6 

IEHINITT 16-2 

IEHIOSUP 17-1 

IEHLIST (VS1) 18-5 

IEHLIST (VS2) 19-5 

IEHMOVE (VS1) 20-9 

IEHMOVE (VS2) 21-9 

IEHPROGM (VS1) 22-9 

IEHPROGM (VS2) 23-5 

IEHUCAT 24-1 

IFHSTATR 25-2 

inserting blocks of records 13-1,13-11 

introduction 

to data set utilities 1-3 

to independent utilities 1-4 

to system utilities 1-3 

invoking utility programs 27-1 

IPL bootstrap records, constructing .... 15-1,15-2,15-4,15-19 
IPLTXT statement 

for IBCDASDI 2-5 

for IEHDASDR 15-19 

IPL program 15-1,15-10 

IPL program records 15-2,15-6 

IPL records, contents 15-5 

IPL records, writing 15-1,15-2,15-5,15-6 

IPL text 2-2,2-5,15-10,15-11,15-19 

italic type, use of viii 



J 

job control statement requirements 1-1 

job control statements for 

IEBCOMPR 5-3 

IEBCOPY 6-6,6-7 

IEBDG 7-4 

IEBEDIT 8-2 

IEBGENER 9-4 

IEBISAM 10-5 

IEBPTPCH 11-3 

IEBTCRIN 12-7 

IEBUPDTE 13-2 

IEHATLAS 14-2 

IEHDASDR 15-7 

IEHINITT 16-2 

IEHIOSUP 17-1 

IEHLIST (VS1) 18-6 

IEHLIST (VS2) 19-5 

IEHMOVE (VS1) 20-10 

IEHMOVE (VS2) 21-9,21-10 

IEHPROGM (VS1) 22-10 

IEHPROGM (VS2) 23-6 

IEHUCAT 24-2 

IFHSTATR 25-2 

JOB statement 

for IBCDASDI 2-2 

for IBCDMPRS 3-1 

for ICAPRTBL 4-1 

job statements in an output data set 8-1 

JOB steps, copying 8-1 

job stream, organizing 8-1 



K 

keywords, combinations of NEW, MEMBER, 
and NAME 



13-9 



L 

label processing 

using IEBCOMPR 5 4,5-5 

using IEBGENER 9-8,9-11 

using IEBPTPCH 11-12 

using IEBTCRIN 12-15 

using IEBUPDTE 13-12,13-13 

using IEHMOVE (VS1) 20-4 

using IEHMOVE (VS2) 21-4 

LABEL statement 

for IEBUPDTE 13-12 

for IEHDASDR 15-14 

labels 

processing user, as data 29-2 

processing user, as data set descriptors 29-1 

LABELS statement 

for IEBCOMPR 5-4 

for IEBGENER 9-8 

for IEBPTPCH 11-12 

labels, volume switch 29-1 

labeling a magnetic tape volume 16-1 

LASTCARD statement 2-6 

levels of index 

creating 22-3 

deleting 22-3,22-4 

libraries, updating symbolic 13-1 

LINK macro instruction 27-1 

linking to an exit routine 27-1 

LIST statement (VS1) 22-21 

LIST statement (VS2) 23-13 
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listing 

a catalog 18-1 

a partitioned data set 11-1,18-1 

a partitioned directory 11-2,18-1 

a password entry (VS1) 22-9,22-21 

a password entry (VS2) 23-5,23-13 

a sequential data set 11-1 

a volume table of contents 18-3 

data set passwords (VSl) 22-9 

data set passwords (VS2) 23-5 

error statistics by volume (ESV) records 25-1 

system control data (VSl) 18-1 

system control data (VS2) 19-1 

LISTCTLG statement 18-7 

LISTPDS statement (VSl) 18-8 

LISTPDS statement (VS2) 19-7 

LISTVTOC statement (VSl) 18-8 

LISTVTOC statement (VS2) 19-8 

LOAD 10-5 

load operation, specified in PARM parameter 10-5 

loading 

an indexed sequential data set 10-3 

an unloaded data set 10-3 

forms control buffer 4-1,4-2 

Universal Character Set buffer 4-1,4-2 

logical record length, changing 9-4 



M 

magnetic tape volumes 

labeling 16-1 

moving a data set to (VSl) 20-11 

moving a data set to (VS2) 21-11 

moving or copying a BDAM data set to (VSl) .... 20-5 
moving or copying a BDAM data set to (VS2) .... 21-5 
moving or copying a BDAM data set from (VSl) . . . 20-5 
moving or copying a BDAM data set from (VS2) . . . 21-5 

moving or copying a group of data sets to 20-7 

moving or copying a volume of data to (VSl) .... 20-8 
moving or copying a volume of data to (VS2) . . . .21-9 
MEMBER, NEW, and NAME keywords, 

combinations of 13-9 

MEMBER statement 

for IEBGENER 9-9 

forlEBPTPCH 11-10 

members, partitioned data set 

comparing 5-1 

copying and merging (VSl) 20-1,6-2 

copying and merging (VS2) 21-1,6-2 

renaming (VSl) 20-1,22-1,6-4 

renaming (VS2) 21-1,23-1,6-4 

replacing (VSl) 6-3,20-1 

replacing (VS2) 6-3,21-1 

scratching (VSl) 22-1 

scratching (VS2) 23-1 

members of a symbolic library 

adding 13-1 

changing 13-1 

methods of executing 

data set utility programs 1-3,1-4 

independent utility programs 1-4 

system utility programs 1-3 

modify selected fields 7-2 

modifying partitioned or sequential data sets 13-1 

mountable devices, defining 28-1 

MOVE CATALOG statement 20-21 

MOVE DSGROUP statement 20-16 

MOVE DSNAME statement (VSl) 20-14 



MOVE DSNAME statement (VS2) 21-13 

MOVE PDS statement (VSl) 20-18 

MOVE PDS statement (VS2) 21-16 

MOVE VOLUME statement (VSl) 20-23 

MOVE VOLUME statement (VS2) 21-17 

moving 

a BDAM data set (VSl) . 20-5 

a BDAM data set (VS2) 21-5 

a catalog 20-8 

a data set (VSl) 20-4 

a data set (VS2) 21-4 

a direct data set with variable spanned records (VSl) . 20-9 
a direct data set with variable spanned records (VS2) . 21-8 

a group of cataloged data sets 20-7 

a multivolume data set (VSl) 20-4,20-9 

a multivolume data set (VS2) 21-5,21-8 

a volume of data sets (VSl) 20-8 

a volume of data sets (VS2) 21-7 

the SYSCTLG data set 20-8 

moving and copying 

data (VSl) 20-1 

data (VS2) 21-1 

user labels (VSl) 20-4 

user labels (VS2) 21-4 

moving and copying operations 

excluding data from (VSl) 6-4,6-13,20-25 

excluding data from (VS2) 6-4,6-13,21-19 

including data in (VSl) 20-24 

including data in (VS2) 21-18 

selecting members for (VSl) 6-2,7-12,20-25 

selecting members for (VS2) 6-2,6-12,21-19 

moving or copying a password protected volume (VSl) . 20-4 
moving or copying a password protected volume (VS2) . 21-4 
MSG statement 

for IBCDASDI 2-2,2-3 

forlBCDMPRS 3-1 

MTDI input 12-1,12-6 

MTST input 12-1,12-6 

multivolume data sets, moving or copying (VSl) . 20-4,20-9 
multivolume data sets, moving or copying (VS2) . . . .21-5 



N 

new master data set 13-1 

NEW, MEMBER, and NAME keywords, 

combinations of 13-9 

nonsharable attribute, assigning 28-1 

nonsharable devices 28-1 

notation for defining control statements viii 

NUMBER 13-9,13-10 

numbering records 13-11 

numeric tape labeling 16-1 

o 

OPEN module, changing or replacing . 17-1 

operand field (on utility control statements) 1-2 

operating procedures for independent utilities 1-4,1-5 

operation field (on utility control statements) 1-2 

order of moved or copied members with the 

IEHMOVE program (VSl) 20-6 

IEHMOVE program (VS2) 21-6 

organizing an input stream 8-1 

output from utility programs (see input to and output from) 
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p 

packed to unpacked decimal conversion 9-10,9-11 

parameter lists of exit routines 26-1,26-2 

parameters passed to exit routines 

for label processing 26-1 

for nonlabel processing 26-2 

PARM information 

with the IEBDG program 7-5 

with the IEBISAM program 10-5 

with the IEBUPDTE program 13-4 

with the IEHDASDR program 15-9 

with the IEHIN1TT program 16-3 

with the IEHLIST program (VS1) 18-7 

with the IEHLIST program (VS2) 19-7 

with the IEHMOVE program (VS1) 20-12 

with the IEHMOVE program (VS2) 21-12 

partial dumps of direct access volumes 15-15,15-17 

partitioned data sets 

comparing ; 5-1 

compressing in place 6-4 

converting to sequential 13-1 

copying (VS1) 6-1,6-2,6-15,6-16,20-4 

copying (VS2) 6-1,6-2,6-15,6-16,21-4 

copying selected members of (VS1) 6-2,6-4,20-25 

copying selected members of (VS2) 6-2,6-4,21-19 

editing (VS1) 9-2,18-1 

editing (VS2) 9-2,19-1 

expanding 9-2 

excluding from move and copy operations (VS1) 6-4,20-25 
excluding from move and copy operations (VS2) 6-4,21-19 

listing (VS1) 18-1 

listing (VS2) 19-1 

loading 6-2 

merging members of (VS1) 6-5,20-6,20-7 

merging members of (VS2) 6-5,21-6,21-7 

moving (VS1) 20-4 

moving (VS2) 21-4 

numbering records in 13-1 

produced from sequential input 13-1 

re-creating 6-5 

renaming (VS1) 22-1,22-13 

renaming (VS2) 23-1,23-8 

replacing records in 13-1,6-4 

unloading (VS1) 20-1 

unloading (VS2) 21-1 

updating in place 13-1 

partitioned data set directory entry, edited format (VS1) . 18-1 

partitioned data set directory entry, edited format (VS2) . 19-1 

partitioned data set directory entry, 
unedited format (VS1) 18-1 

partitioned data set directory entry, 

unedited format (VS2) 19-2 

partitioned data set directory, listing 18-1 

dump format 18-2 

edited format 18-1 

unedited format 18-2 

PASSWORD data set 

adding entries to (VS1) 22-8 

adding entries to (VS2) 23-4 

deleting entries from (VS1) 22-8 

deleting entries from (VS2) 23-4 

listing entries in (VS1) 22-9 

listing entries in (VS2) 23-5 

maintaining entries in (VS1) 22-6 

maintaining entries in (VS2) 23-2 

replacing entries in (VS1) 22-8 

replacing entries in (VS2) 23-4 



password protected data sets, IEHDASDR 15-8 

password protected volumes, moving or copying (VS1) . . 20-4 
password protected volumes, moving or copying (VS2) . .21-4 
passwords, data set 

adding (VS1) 22-8 

adding (VS2) 23-4 

deleting (VS1) 22-8 

deleting (VS2) 23-4 

listing (VS1) 22-9 

listing (VS2) 23-5 

maintaining (VS1) 22-6 

maintaining (VS2) 23-2 

replacing (VS1) 22-8 

replacing (VS2) 23-4 

patterns of test data 7-1 

picture, user-specified 7-2 

prerequisite publications vii 

print specifications 

standard 11-1 

user 11-1 

PRINT statement 11-4 

printing 

a partitioned directory (VS1) 11-2,11-3,18-1 

a partitioned directory (VS2) 11-2,11-3,19-1 

an edited data set 11-2 

data sets 11-1 

indexed sequential data sets 10-3 

partitioned data sets 11-1 

selected records 11-2 

selected members 11-1 

sequential data set 11-1 

PRINTL 10-5 

private attribute, assigning 28-1 

procedure library, entering procedures in 13-1,13-15 

procedures, cataloging 13-1,13-15 

processing user labels 29-1 

as data 29-2 

program classes 

data set 1-3 

independent 1-4 

system 1-3 

program selection xxv 

protecting data sets (see IEHPROGM utility program) 
punch specifications 

standard 11-1 

user 11-1 

PUNCH statement 11-6 

punching 

records 11-1,11-2 

partitioned data sets 11-1.11-2 

sequential data sets 11-1,11-2 

punctuation, use of in control statements viii 

purging unexpired data sets 

ANALYZE operation 15-10 

DUMP operation 15-15 

FORMAT operation 15-12 

RESTORE operation 15-18 

PUTIPL statement 15-19 

Q 

Quick-DASDl 2-1,15-12,15-28 
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R 

reblocking 

with IEBCOPY 6-7 

with IEBGENER 9-4 

with IEHMOVE (VS1) 20-4 

with IEHMOVE (VS2) 21-4 

RECORD statement 

for IEBGENER 9-9 

for IEBPTPCH 11-10 

record groups, assigning 9-1 

records 

adding 13-10 

assigning sequence numbers to 13-10 

comparing 5-1 

copying 9-4 

deleting 13-9,13-10 

error 12-1,12-3 

error statistic by volume 25-1 

ESV 25-1 

printing 11-1,11-2,11-4 

punching 11-1,11-2,11-6 

renumbering 13-10 

replacing 13-11 

re-creating a data set (VS1) 6-5,20-1 

re-creating a data set (VS2) 6-5,21-1 

related publications vii 

RELEASE statement 22-17 

releasing two volumes 22-4,22-17 

removable volumes, allocating 28-1 

removing entries from an index structure . 22-2,22-3,22-4,22-5 

RENAME statement (VS1) 22-13 

RENAME statement (VS2) 23-8 

renaming 

a data set (VSI) 22-1,22-13 

a data set (VS2) 23-1,23-8 

a member (VSI) 22-1,22-13 

a member (VS2) 23-1,23-8 

a multivolume data set 22-13,23-8 

selected numbers 6-4 

renumbering logical records 13-1 

REPEAT statement 7-15 

REPL (IEBUPDTE) 13-5 

REPLACE statement 

for IEHMOVE (VSI) 20-26 

for IEHMOVE (VS2) 21-20 

for IEHPROGM (VSI) 22-19 

for IEHPROGM (VS2) 23-11 

replacement data records 13-11,13-12 

replacing 

data set passwords (VSI) 22-8,22-19 

data set passwords (VS2) 23-4,23-11 

identically named members 6-3 

logical records 13-1 

members in move and copy operations (VSI) 6-2,6-3,20-1 
members in move and copy operations (VS2) 6-2,6-3,21-1 

members of a symbolic library 13-1 

records in a partitioned data set 13-1,6-2,6-3 

selected members 6-2,6-3 

REPRO (IEBUPDTE) 13-5 

reproducing members of a symbolic library 13-5 

required publications vii 

requirements, job control statement 1-1 

RESTORE statement 

forlBCDMPRS 3-4 

for IEHDASDR 15-18 

restoring data to a direct access volume 3-1 

restoring unlike devices 15-4 

restrictions on utility control statements 1-2 



RETURN macro instruction 26-2 

return codes 

for IEBCOMPR 5-2 

for IEBCOPY 6-6 

for IEBDG 7-3 

for IEBEDIT 8-1 

for IEBGENER 9-4 

for IEiRISAM 10-4 

for IEBPTPCH 11-2 

forlEBTCRIN 12-16 

for IEBUPDTE 13-2 

for IEHDASDR 15-6 

for IEHINITT 16-2 

for IEHIOSUP 17-1 

for IEHLIST (VSI) 18-5 

for IEHLIST (VS2) 19-5 

for IEHMOVE (VSI) . 20-10 

for IEHMOVE (VS2) 21-9 

for IEHPROGM (VSI) 22-9 

for IEHPROGM (VS2) 23-5 

return codes, action on 26-4 

return codes issued by user exit routines 26-4 

return codes issued by user totaling routines 29-2 

returning from an exit routine 26-2 

s 

SCRATCH module, changing or replacing 17-1 

SCRATCH statement (VSI) 2212 

SCRATCH statement (VS2) 23-7 

scratching 

a data set (VSI) 22-1 

a data set (VS2) 23-1 

a member (VSI) 22-1 

a member (VS2) 23-1 

a volume table of contents entry (VSI) .... 22-1,22-12 
a volume table of contents entry (VS2) .... 23-1,23-8 
secondary passwords 

adding (VSI) . 22-7,22-8,22-18 

adding (VS2) 23-3,23-4,23-10 

deleting (VSI) 22-8,22-20 

deleting (VS2) 23-4,23-12 

listing (VSI) 22-9 

listing (VS2) 23-5 

replacing (VSI) 22-19 

replacing (VS2) 23-11 

SELECT statement 

for IEBCOPY 6-12 

for IEHMOVE (VSI) 20-25 

for IEHMOVE (VS2) 21-19 

selecting a program xxv 

selecting members to be loaded or unloaded 6-2 

selecting members to be moved or copied 6-2 

selective 

copy 6-2 

rename 6-4 

replace 6-4 

sequence numbers, assigning (VSI) 20-11 

sequence numbers, assigning (VS2) 21-11 

sequential data sets 

comparing 5-1 

compressing 6-4 

converting to partitioned 13-1 

creating 10-1,10-3,8-1,12-1 

editing 8-1,12-5,12-1 

printing 11-1 

punching 11-1 

unloading (VSI) 20-1 
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unloading (VS2) 21-1 

sequential output job stream, creating 10-1,10-3,8-1 

SETPRT module, changing or replacing 17-1 

sharing mountable devices 28-2 

simultaneous IEHDASDR operations 15-8 

SOR 12-2,12-3 

space allocation by IEHMOVE (VS1) 20-1,20-11 

space allocation by IEHMOVE (VS2) 21-1,21-11 

specific request for mountable volumes 28-1 

specific volumes, making requests for 28-1 

specifying an expiration date (VS1) 20-11 

specifying an expiration date (VS2) 21-11 

spill data sets, used with IEBCOPY 6-6 

standard print operation 11-1 

standard punch operation 11-1 

STOW module, changing or replacing . . 17-1 

straight copy 6-1 

surface analysis of direct access volumes 15-1,15-10 

SVC library, moving 17-1 

symbolic libraries, updating 13-1 

SYSCTLG data set 

creating (VS1) 22-2,22-4 

creating (VS2) 23-1 

moving or copying 20-8 

system control data, listing (VS1) 18-1 

system control data, listing (VS2) 19-1 

system status information 13-8 

system utility programs 

IEHATLAS 14-1 

IEHDASDR 15-1 

IEHINITT 16-1 

IEHIOSUP 17-1 

IEHLIST (VS1) 18-1 

IEHLIST (VS2) 19-1 

IEHMOVE (VS1) 20-1 

IEHMOVE (VS2) 21-1 

IEHPROGM (VS1) 22-1 

IEHPROGM (VS2) 23-1 

IEHUCAT 24-1 

IFHSTATR 25-1 

introduction 1-3 

T 

tape volumes, labeling 16-1,16-2 

tapemark in a volume label set 16-1 

TCLOSE module, changing or replacing 17-1 

TCRGEN statement 12-8 

test data 

generating 7-1 

patterns of 7-1 

TITLE statement 11-9 

totaling routine return codes, user 29-2 

TRACK statement 14-2 

track overflow feature 

with IEHMOVE (VS1) 20-13 

with IEHMOVE (VS2) 21-12 

tracks (see alternate tracks and defective tracks) 

dumping 15-3 

getting alternate 15-1,2-1 

transfer control tables, updating 17-1 

TTR entries, updating 17-1 

type 21 record processing 25-1,25-2 



u 

UCS 

loading of 4-1 

statement 4-2 

uncataloging a data set (VS1) 22-2 

uncataloging a data set (VS2) 23-2 

UNCATLG statement (VS1) 22-14 

UNCATLG statement (VS2) 23-10 

underscore, use of ix 

unexpired data sets encountered 

during ANALYZE operation 15-12 

during DUMP operation 15-17 

during FORMAT operation 15-14 

during RESTORE operation 15-19 

Universal Character Set buffer, loading the 4-1,4-2 

unlike devices 

dumping 15-4 

restoring 15-4 

UNLOAD 10-5 

unloaded data 10-1 

unloaded data sets 

creating 10-1 

loading 10-1,10-3 

reconstructing 10-3 

format of (IEBISAM) 10-2 

unloading 

indexed sequential data set 10-1 

partitioned data set (VS1) 20-1 

partitioned data set (VS2) 21-1 

sequential data set (VS1) 20-1 

sequential data set (VS2) 21-1 

unmovable data sets, moving or copying (VS1) 20-1 

unmovable data sets, moving or copying (VS2) 21-1 

unpacked to packed decimal conversion 9-10,9-11 

updating 

symbolic libraries 13-1 

transfer control tables 17-1 

TTR entries in the SVC library 17-1 

updating in place, a partitioned data set 13-3 

user exits (see exit routines) 
user labels 

as data 29-2 

as data set descriptors 29-1 

copying (VS1) 20-4 

copying (VS2) 21-4 

EXITS statement 

for IEBCOMPR 5-4 
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for IEBPTPCH 11-9 
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for IEBPTPCH 11-10 
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DUMP 15-15 
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LISTVTOC (VSI) 18-8 
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COPY PDS (VSI) 20-19 
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